Вебхуки

Вебхук — 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

object (WebhookDataClientUpdated)

client.updated — только изменённые поля с новыми значениями

client_branch_profile_idintegerобязательный

Пример: 730112

fieldsobjectобязательный

namestring

Пример: John Doe

genderstring

Значения:womanman

Пример: man

date_of_birthstringможет быть null

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

Пример: 1982-01-03

object (WebhookDataClientBonusesChanged)

client.bonuses_changed — баланс не передаётся, его нужно получить через API

client_branch_profile_idintegerобязательный

Пример: 730112

operationstringобязательный

Значения:accrualwithdrawalcancellationdecreaserefundexpiration

Пример: accrual

sumnumberобязательный

На сколько изменился баланс; при сгорании — неизрасходованный остаток бонусов

Пример: 150

order_idintegerможет быть null

Пример: 1204551

client_bonus_idintegerможет быть null

Пример: 88120

date_availablestringможет быть null

Для отложенного начисления — когда бонусы станут доступны

Пример: 2026-09-26 12:00:00

object (WebhookDataOrderCreated)

order.created — карточка заказа в том виде, в каком её возвращает orders.edit, и order_id; предоплаченный заказ приходит только после оплаты

idintegerобязательный

Пример: 12863367

meta_authorized_clientboolean

Пример: true

meta_sitestring

Пример: shop.foodsoul.pro

meta_utm_sourcestring

Пример: shop.foodsoul.pro

meta_utm_mediumstring

Пример: shop.foodsoul.pro

meta_utm_campaignstring

Пример: shop.foodsoul.pro

meta_utm_contentstring

Пример: shop.foodsoul.pro

meta_utm_termstring

Пример: shop.foodsoul.pro

cart_bodyobject

delivery_feeinteger

Пример: 100

courier_feenumber

Пример: 100

service_feenumber

Пример: 100

itemsarray of objectобязательный

idintegerобязательный

Пример: 94060278

item_namestring

Пример: Item 100

item_parameter_measurestring

Пример: 1 pc

countintegerобязательный

Пример: 1

amountnumber

Пример: 1000

new_costnumber

Пример: 1000

category_namestring

Пример: Sushi rolls

imagestring

Пример: https://cdn.crm.git.foodsoul.dev/zones/ru/branches/8920/images/items/medium/fda311c7e13e4abf049a271cb885c11e.jpg?v1735116559

settingsobjectобязательный

discountboolean

Пример: true

free_deliveryboolean

Пример: true

minimum_sumboolean

Пример: true

modifiers_multiplierboolean

Пример: true

stock_balanceboolean

Пример: true

offersarray of object

idstringобязательный

Пример: 152366

namestringобязательный

Пример: 15%

typestring (TypeWorkOperatingMode) обязательный

Значения:fixed_discount_on_all_orderpercent_discount_on_all_orderfixed_discount_on_items_from_categoriespercent_discount_on_items_from_categoriesfixed_discount_on_itemspercent_discount_on_itemsfree_item_to_choose_if_buy_itemsfree_item_to_choose_if_buy_items_from_categoriesfixed_discount_on_next_itempercent_discount_on_next_itemfixed_discount_on_next_item_from_categoriespercent_discount_on_next_item_from_categoriesfree_item_to_choosepercent_discount_on_item_with_minimum_cost_in_cartfixed_discount_on_item_with_minimum_cost_in_cartpercent_discount_on_item_with_minimum_cost_from_itemsfixed_discount_on_item_with_minimum_cost_from_itemspercent_discount_on_item_with_minimum_cost_from_categoriesfixed_discount_on_item_with_minimum_cost_from_categoriesbonusesfree_delivery

Пример: free_delivery

promoobject

↻ дальше не раскрываем

discountobject

↻ дальше не раскрываем

record_idstring

Пример: 1115346

modestring

Пример: percent_discount_on_all_order

modifiersarray of object

idintegerобязательный

Пример: 31369618

namestringобязательный

Пример: Modifier without a group

amountintegerобязательный

Пример: 0

new_costinteger

Пример: 0

sum_one_modifier_with_countnumber

Пример: 0

countintegerобязательный

Пример: 1

integerinteger

Пример: 1

item_contentarray of object

additional_modifiersarray of string

↻ дальше не раскрываем

total_sum_modifiersstring

Пример: 5

total_sum_itemstring

Пример: 100 + 5 = 105

special_offerstring

Пример: -10% on pickup

discountstring

Пример: 10% (items: 4)

sum_one_itemnumber

Пример: 105

finish_sumnumber

Пример: 378

total_modifiersnumber

Пример: 100

sum_one_item_with_countnumber

Пример: 100

sum_one_item_with_modifiersnumber

Пример: 100

formulanumber

Пример: 100

has_modifiers_multiplierboolean

Пример: true

sum_discount_for_itemnumber

Пример: 100

sum_item_finish_mathnumber

Пример: 252.24

bonusesobject

accrualobject

sumnumber

Пример: 0.05

withdrawobject

sumnumber

Пример: 0.05

pickup_namestring

Пример: Voronezh-Center

pickup_addressstring

Пример: Voronezh

operator_phonestring

Пример: +7 (999) 999-95-95

courier_service_enabledbooleanобязательный

Пример: true

courier_button_showedbooleanобязательный

Пример: true

payment_namestring

Пример: IOKassa: Visa / MasterCard / MIR

email_settingsobject

format_addressboolean

Пример: true

lite_versionboolean

Пример: true

include_photoboolean

Пример: true

permanent_clientboolean

Пример: true

client_account_idinteger

Пример: 4211394

client_branch_profile_idinteger

Пример: 49000070

api_versioninteger

Пример: 1

authorized_clientboolean

Пример: true

synchronization_idstring

Пример: f6bb7673-ad2d-4b46-9545-2b0a8b37fd29

meta_user_agentstring

Пример: FSShop v8.1.2, iOS v18.5, Device: iPad8,6

application_uuidstring

Пример: 03addc0d-1051-4534-9ba8-792b763a274b

additional_contactless_serviceboolean

Пример: true

additional_cutleryboolean

Пример: true

additional_not_callbackboolean

Пример: true

additional_expedited_deliveryboolean

Пример: true

sum_in_cartnumber

Пример: 100

notesarray of object

datestring (DataTimeFormatSQL)

Пример: 2024-05-02 08:31:16

textstring

Пример: Status set to confirmed by the automatic order confirmation system

transactionsarray of object

statusstring

Значения:confirmedrefunded

Пример: confirmed

datestring (DataTimeFormatSQL)

Пример: 2024-05-02 08:31:16

sumnumber

Пример: 500

order_statusstring (OrderStatus) обязательный

Статус заказа: в пути, выполнен, сборка, на кухне, не обработан, готов к отправке, ожидает отправки на кухню, ожидает переделки, отменён, подтверждён, приготовлен

Значения:in_transitdoneassemblyin_kitchennot_processedready_to_transitwait_to_kitchenwait_remadecanceledconfirmedcooked

Пример: confirmed

minutes_to_doneinteger

Пример: 60

date_preorderstring (DataTimeFormatSQL)

Пример: 2024-05-02 08:31:16

timestamp_countdownintegerобязательный

Пример: 1718625496

branch_idintegerобязательный

Пример: 9054

sms_statusstring (OrderSmsStatus) обязательный

Статус SMS

Значения:errorsuccessempty_fieldswrong_phonewrong_api_fieldsserver_not_availablenot_enough_moneywaitingneed_phoneoperators_not_connected_to_botssend_via_bots_failedsending_via_botssent_via_botssent_via_maxsent_via_telegramunsupported_sms_serviceapi_disabledwrong_sender_name

email_statusstring (OrderEmailStatus) обязательный

Статус email

Значения:errorwaitingsuccessneed_email

cart_totalnumberобязательный

Пример: 100.55

order_numberintegerобязательный

Пример: 154

date_creationstring (DataTimeFormatSQL) обязательный

Пример: 2024-05-02 08:31:16

payment_statusstringобязательный

Значения:paidnot_paid

Пример: not_paid

payment_methodstring (OrderPaymentMethod)

Способ оплаты

Значения:cashonlinecard_upon_receipt

platformstring (Platform) обязательный

Значения:androidiosallmobile_appssitesocial_apps

Пример: all

operator_phone_format_idinteger (PhoneFormatId)

Код страны: 1-🇷🇺(+7|8), 2-🇦🇿(+994|0), 3-🇧🇾(+375|80), 4-🇰🇿(+7|8), 6-🇷🇸(+381|0), 7-🇹🇷(+90|0), 8-🇺🇦(+380|0), 9-🇵🇹(+351|0), 10-🇰🇬(+996|0), 11-🇺🇸(+1), 12-🇫🇷(+33|0), 13-🇲🇩(+373|0), 15-🇪🇪(+372), 18-🇬🇪(+995), 19-🇺🇿(+998), 22-🇵🇱(+48|0), 23-🇹🇯(+992|8), 25-🇷🇴(+40|0), 44-🇨🇭(+41|0)

Пример: 1

operator_phone_numberstring

Пример: 9114579423

operator_emailstring

Пример: email@example.com

percent_rateintegerобязательный

Пример: 4

sender_namestring

Пример: John Doe

sender_phone_format_idinteger (PhoneFormatId)

Пример: 1

sender_phone_numberstring

Пример: 9114579423

sender_emailstring

Пример: email@example.com

recipient_namestring

Пример: John Doe

recipient_phone_format_idinteger (PhoneFormatId)

Пример: 1

recipient_phone_numberstring

Пример: 9114579423

address_zip_codestring

Пример: 236039

address_line_1string

Пример: Korablestroiteley st. 9 bld. 2

address_line_2string

Пример: Korablestroiteley st. 9 bld. 2

address_streetstring

Пример: Partizanskaya street

address_housestring

Пример: 20

address_buildingstring

Пример: 20

address_entrance_numberstring

Пример: 20

address_entrance_codestring

Пример: 1234

address_floorstring

Пример: 10

address_apartmentstring

Пример: 10

additional_changestring

Пример: 100

additional_personsstring

Пример: 2

additional_commentstring

Пример: Test order, remove

additional_greeting_cardstring

Пример: example

additional_discountstring

Пример: example

tokenstring

Пример: 72901fbe661d3e142ea9af5248856f20

delivery_methodstring (DeliveryMethod) обязательный

Способ доставки: no — нет, all — все, courier — курьер, pickup — самовывоз

Значения:noallcourierpickup

phone_settingsobject

mask_enableboolean

Пример: true

formatboolean

Пример: true

internationalboolean

Пример: true

branch_namestring

Пример: Green Basket | Main

chain_namestringобязательный

Пример: Green Basket

city_namestringобязательный

Пример: Voronezh

district_namestring

Пример: Voronezh-Uh

district_idinteger

Пример: 55329

order_idintegerобязательный

Пример: 1204551

object (WebhookDataOrderStatusChanged)

order_idintegerобязательный

Пример: 1204551

order_numberintegerможет быть null

Пример: 154

order_statusstringобязательный

Пример: confirmed

previous_order_statusstringможет быть null

Пример: not_processed

object (WebhookDataOrderPaymentStatusChanged)

order_idintegerобязательный

Пример: 1204551

order_numberintegerможет быть null

Пример: 154

payment_statusstringобязательный

Значения:paidrefunded

Пример: paid

sumnumber

Только для refunded

Пример: 1250

object (WebhookDataFeedbackCreated)

feedback_idintegerобязательный

Пример: 40211

order_idintegerможет быть null

Пример: 1204551

client_branch_profile_idintegerможет быть null

Пример: 730112

textstringобязательный

Пример: Everything was hot and on time

statusstringобязательный

Значения:positivenegative

Пример: positive

platformstringможет быть null

Значения:iosandroidsitevkapifb

Пример: site

imagestringможет быть null

Пример: https://cdn.foodsoul.pro/zones/ru/branches/8412/images/feedback/3f2a.jpg

object (WebhookDataCourierAssigned)

order_idintegerобязательный

Пример: 1204551

order_numberintegerможет быть null

Пример: 154

courier_idintegerобязательный

Пример: 5120

object (WebhookDataItemStopListChanged)

item.stop_list_changed — одно событие на каждое изменение; идентификаторы параметров товара (размеров)

item_parameter_ids_addedarray of integerобязательный

item_parameter_ids_removedarray of integerобязательный

object (WebhookDataBranchWorkStatusChanged)

branch.work_status_changed — филиал остановил или возобновил приём заказов

blockedbooleanобязательный

Пример: true

noticestringможет быть null

Пример: Технический перерыв до 15:00

Пример тела

{
  "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`	Не принято, доставка повторяется