API

Вебхуки

Вебхук — це HTTP-запит, який FoodSoul надсилає на адресу вашої системи, коли в акаунті відбувається подія: нове замовлення, зміна статусу, відгук та інші.

Підписка з адресою та подіями створюється методом:

POST Створити підписку на вебхук

Адрес — URL із підписки, метод — POST.

Формат, підпис і повтори

Тіло запиту вебхука. Кожен запит — POST з Content-Type: application/json на URL підписки. URL має починатися з https. Заголовки: X-Webhook-Event — код події, X-Webhook-ID — event_uuid, X-Webhook-Signature — sha256= та HMAC-SHA256 вихідного тіла запиту в hex з секретом філії (webhooks_subscriptions.generate_secret). Перевіряйте підпис за вихідним тілом до розбору JSON: hash_equals(hash_hmac('sha256', $body, $secret), substr($signature, 7)). Мітки часу у підписі немає, канал захищений HTTPS. Доставка вважається прийнятою при будь-якій відповіді 2xx протягом 10 секунд. Редіректи не виконуються. Інакше доставка повторюється: 7 спроб, перша одразу, далі через 1, 5, 15, 60, 180 та 360 хвилин. Усі спроби однієї доставки містять однаковий X-Webhook-ID. Повторна відправка з журналу (webhooks_logs.resend) містить той самий X-Webhook-ID — за ним пропускайте вже оброблені доставки. 20 невдалих доставок поспіль відключають підписку (blocked), а власник і системний адміністратор акаунта отримують лист. webhooks_subscriptions.unblock вмикає підписку знову. Тіло містить дані події: клієнт, відгук і картка замовлення передаються повністю. Бонусний баланс не передається: він спільний для пулу мереж, його потрібно отримати через API.

Заголовки

X-Webhook-Eventstringобов’язковий

Приклад: order.created

X-Webhook-IDstringобов’язковий

Приклад: 5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41

X-Webhook-Signaturestringобов’язковий

Приклад: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Події

  • client.registered
  • client.updated
  • client.bonuses_changed
  • order.created
  • order.status_changed
  • order.payment_status_changed
  • feedback.created
  • courier.assigned
  • item.stop_list_changed
  • branch.work_status_changed

Тіло запиту

object (WebhookPayload)
eventstringобов’язковий

Значення:client.registeredclient.updatedclient.bonuses_changedorder.createdorder.status_changedorder.payment_status_changedfeedback.createdcourier.assigneditem.stop_list_changedbranch.work_status_changed

Приклад: order.status_changed

event_uuidstringобов’язковий

Приклад: 5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41

date_creationstring (DataTimeFormatSQL) обов’язковий

Приклад: 2024-05-02 08:31:16

branch_idintegerобов’язковий

Приклад: 8412

dataoneOfобов’язковий
Один із варіантів
object (WebhookDataClientRegistered)

client.registered — новий телефон або перший вхід акаунта в цьому філіалі

client_branch_profile_idintegerобов’язковий

Приклад: 730112

namestringможе бути null

Приклад: John Doe

phonestringобов’язковий

Телефон у міжнародному форматі, без форматування

Приклад: +79114579423

genderstringможе бути null

Значення:womanman

Приклад: man

date_of_birthstringможе бути null

Дата народження у форматі Y-m-d

Приклад: 1982-01-03

Приклад тіла

{
  "event": "order.status_changed",
  "event_uuid": "5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41",
  "date_creation": "2024-05-02 08:31:16",
  "branch_id": 8412,
  "data": {
    "client_branch_profile_id": 730112,
    "name": "John Doe",
    "phone": "+79114579423",
    "gender": "man",
    "date_of_birth": "1982-01-03"
  }
}

Відповідь вашої системи

2XX

Прийнято

default

Не принято, доставка повторяется