Webhooks

A webhook is an HTTP request that FoodSoul sends to your system's address when an event occurs in your account: a new order, status change, review, and others.

A subscription with an address and events is created using the method:

POST Create a webhook subscription

The address is the URL from the subscription, the method is POST.

Format, signature, and repetitions

Webhook request body. Each request is a POST with Content-Type: application/json to the subscription URL. The URL must start with https.
Headers:

X-Webhook-Event — event code
X-Webhook-ID — event_uuid
X-Webhook-Signature — sha256= and HMAC-SHA256 of the original request body in hex, using the branch secret (webhooks_subscriptions.generate_secret).
Verify the signature against the original body before parsing JSON: hash_equals(hash_hmac('sha256', $body, $secret), substr($signature, 7)). There is no timestamp in the signature; the channel is protected by HTTPS.

Delivery is considered accepted with any 2xx response within 10 seconds. Redirects are not followed. Otherwise, delivery is retried: 7 attempts — first immediately, then after 1, 5, 15, 60, 180, and 360 minutes. All attempts for a single delivery use the same X-Webhook-ID. Resending from the log (webhooks_logs.resend) uses the same X-Webhook-ID — use it to skip already processed deliveries.

20 consecutive failed deliveries disable the subscription (blocked), and both the owner and the account system administrator receive an email. webhooks_subscriptions.unblock re-enables the subscription.

The body contains event data: client, review, and order card are sent in full. Bonus balance is not included: it is shared across the network pool and must be retrieved via API.

Headers

X-Webhook-Eventstringrequired

Example: order.created

X-Webhook-IDstringrequired

Example: 5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41

X-Webhook-Signaturestringrequired

Example: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Events

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

Request body

object (WebhookPayload)

eventstringrequired

Values:client.registeredclient.updatedclient.bonuses_changedorder.createdorder.status_changedorder.payment_status_changedfeedback.createdcourier.assigneditem.stop_list_changedbranch.work_status_changed

Example: order.status_changed

event_uuidstringrequired

Example: 5f0c6b1e-6a1d-4c1e-9d6b-3a7f0e2b8c41

date_creationstring (DataTimeFormatSQL) required

Example: 2024-05-02 08:31:16

branch_idintegerrequired

Example: 8412

dataoneOfrequired

One of the options

object (WebhookDataClientRegistered)

client.registered — new phone number or first account login in this branch

client_branch_profile_idintegerrequired

Example: 730112

namestringcan be null

Example: John Doe

phonestringrequired

Phone number in international format, without formatting

Example: +79114579423

genderstringcan be null

Values:womanman

Example: man

date_of_birthstringcan be null

Date of birth in Y-m-d format

Example: 1982-01-03

object (WebhookDataClientUpdated)

client.updated — only the changed fields with new values

client_branch_profile_idintegerrequired

Example: 730112

fieldsobjectrequired

namestring

Example: John Doe

genderstring

Values:womanman

Example: man

date_of_birthstringcan be null

Date of birth in Y-m-d format

Example: 1982-01-03

object (WebhookDataClientBonusesChanged)

client.bonuses_changed — the balance is not provided; it must be retrieved via the API

client_branch_profile_idintegerrequired

Example: 730112

operationstringrequired

Values:accrualwithdrawalcancellationdecreaserefundexpiration

Example: accrual

sumnumberrequired

The amount by which the balance changed; in case of expiration — the unused bonus balance

Example: 150

order_idintegercan be null

Example: 1204551

client_bonus_idintegercan be null

Example: 88120

date_availablestringcan be null

For delayed accrual — when the bonuses become available

Example: 2026-09-26 12:00:00

object (WebhookDataOrderCreated)

order.created — the order card as returned by orders.edit, and order_id; a prepaid order is sent only after payment

idintegerrequired

Example: 12863367

meta_authorized_clientboolean

Example: true

meta_sitestring

Example: shop.foodsoul.pro

meta_utm_sourcestring

Example: shop.foodsoul.pro

meta_utm_mediumstring

Example: shop.foodsoul.pro

meta_utm_campaignstring

Example: shop.foodsoul.pro

meta_utm_contentstring

Example: shop.foodsoul.pro

meta_utm_termstring

Example: shop.foodsoul.pro

cart_bodyobject

delivery_feeinteger

Example: 100

courier_feenumber

Example: 100

service_feenumber

Example: 100

itemsarray of objectrequired

idintegerrequired

Example: 94060278

item_namestring

Example: Item 100

item_parameter_measurestring

Example: 1 pc

countintegerrequired

Example: 1

amountnumber

Example: 1000

new_costnumber

Example: 1000

category_namestring

Example: Sushi rolls

imagestring

Example: https://cdn.crm.git.foodsoul.dev/zones/ru/branches/8920/images/items/medium/fda311c7e13e4abf049a271cb885c11e.jpg?v1735116559

settingsobjectrequired

discountboolean

Example: true

free_deliveryboolean

Example: true

minimum_sumboolean

Example: true

modifiers_multiplierboolean

Example: true

stock_balanceboolean

Example: true

offersarray of object

idstringrequired

Example: 152366

namestringrequired

Example: 15%

typestring (TypeWorkOperatingMode) required

Values: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

Example: free_delivery

promoobject

↻ we won't reveal any further

discountobject

↻ we won't reveal any further

record_idstring

Example: 1115346

modestring

Example: percent_discount_on_all_order

modifiersarray of object

idintegerrequired

Example: 31369618

namestringrequired

Example: Modifier without a group

amountintegerrequired

Example: 0

new_costinteger

Example: 0

sum_one_modifier_with_countnumber

Example: 0

countintegerrequired

Example: 1

integerinteger

Example: 1

item_contentarray of object

additional_modifiersarray of string

↻ we won't reveal any further

total_sum_modifiersstring

Example: 5

total_sum_itemstring

Example: 100 + 5 = 105

special_offerstring

Example: -10% on pickup

discountstring

Example: 10% (items: 4)

sum_one_itemnumber

Example: 105

finish_sumnumber

Example: 378

total_modifiersnumber

Example: 100

sum_one_item_with_countnumber

Example: 100

sum_one_item_with_modifiersnumber

Example: 100

formulanumber

Example: 100

has_modifiers_multiplierboolean

Example: true

sum_discount_for_itemnumber

Example: 100

sum_item_finish_mathnumber

Example: 252.24

bonusesobject

accrualobject

sumnumber

Example: 0.05

withdrawobject

sumnumber

Example: 0.05

pickup_namestring

Example: Voronezh-Center

pickup_addressstring

Example: Voronezh

operator_phonestring

Example: +7 (999) 999-95-95

courier_service_enabledbooleanrequired

Example: true

courier_button_showedbooleanrequired

Example: true

payment_namestring

Example: IOKassa: Visa / MasterCard / MIR

email_settingsobject

format_addressboolean

Example: true

lite_versionboolean

Example: true

include_photoboolean

Example: true

permanent_clientboolean

Example: true

client_account_idinteger

Example: 4211394

client_branch_profile_idinteger

Example: 49000070

api_versioninteger

Example: 1

authorized_clientboolean

Example: true

synchronization_idstring

Example: f6bb7673-ad2d-4b46-9545-2b0a8b37fd29

meta_user_agentstring

Example: FSShop v8.1.2, iOS v18.5, Device: iPad8,6

application_uuidstring

Example: 03addc0d-1051-4534-9ba8-792b763a274b

additional_contactless_serviceboolean

Example: true

additional_cutleryboolean

Example: true

additional_not_callbackboolean

Example: true

additional_expedited_deliveryboolean

Example: true

sum_in_cartnumber

Example: 100

notesarray of object

datestring (DataTimeFormatSQL)

Example: 2024-05-02 08:31:16

textstring

Example: Status set to confirmed by the automatic order confirmation system

transactionsarray of object

statusstring

Values:confirmedrefunded

Example: confirmed

datestring (DataTimeFormatSQL)

Example: 2024-05-02 08:31:16

sumnumber

Example: 500

order_statusstring (OrderStatus) required

Order status: on the way, completed, assembling, in the kitchen, not processed, ready for dispatch, waiting to be sent to kitchen, waiting for remake, cancelled, confirmed, prepared

Values:in_transitdoneassemblyin_kitchennot_processedready_to_transitwait_to_kitchenwait_remadecanceledconfirmedcooked

Example: confirmed

minutes_to_doneinteger

Example: 60

date_preorderstring (DataTimeFormatSQL)

Example: 2024-05-02 08:31:16

timestamp_countdownintegerrequired

Example: 1718625496

branch_idintegerrequired

Example: 9054

sms_statusstring (OrderSmsStatus) required

SMS status

Values: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) required

Email status

Values:errorwaitingsuccessneed_email

cart_totalnumberrequired

Example: 100.55

order_numberintegerrequired

Example: 154

date_creationstring (DataTimeFormatSQL) required

Example: 2024-05-02 08:31:16

payment_statusstringrequired

Values:paidnot_paid

Example: not_paid

payment_methodstring (OrderPaymentMethod)

Payment method

Values:cashonlinecard_upon_receipt

platformstring (Platform) required

Values:androidiosallmobile_appssitesocial_apps

Example: all

operator_phone_format_idinteger (PhoneFormatId)

Country code: 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)

Example: 1

operator_phone_numberstring

Example: 9114579423

operator_emailstring

Example: email@example.com

percent_rateintegerrequired

Example: 4

sender_namestring

Example: John Doe

sender_phone_format_idinteger (PhoneFormatId)

Example: 1

sender_phone_numberstring

Example: 9114579423

sender_emailstring

Example: email@example.com

recipient_namestring

Example: John Doe

recipient_phone_format_idinteger (PhoneFormatId)

Example: 1

recipient_phone_numberstring

Example: 9114579423

address_zip_codestring

Example: 236039

address_line_1string

Example: Korablestroiteley st. 9 bld. 2

address_line_2string

Example: Korablestroiteley st. 9 bld. 2

address_streetstring

Example: Partizanskaya street

address_housestring

Example: 20

address_buildingstring

Example: 20

address_entrance_numberstring

Example: 20

address_entrance_codestring

Example: 1234

address_floorstring

Example: 10

address_apartmentstring

Example: 10

additional_changestring

Example: 100

additional_personsstring

Example: 2

additional_commentstring

Example: Test order, remove

additional_greeting_cardstring

Example: example

additional_discountstring

Example: example

tokenstring

Example: 72901fbe661d3e142ea9af5248856f20

delivery_methodstring (DeliveryMethod) required

Delivery method: no — none, all — all, courier — courier, pickup — pickup

Values:noallcourierpickup

phone_settingsobject

mask_enableboolean

Example: true

formatboolean

Example: true

internationalboolean

Example: true

branch_namestring

Example: Green Basket | Main

chain_namestringrequired

Example: Green Basket

city_namestringrequired

Example: Voronezh

district_namestring

Example: Voronezh-Uh

district_idinteger

Example: 55329

order_idintegerrequired

Example: 1204551

object (WebhookDataOrderStatusChanged)

order_idintegerrequired

Example: 1204551

order_numberintegercan be null

Example: 154

order_statusstringrequired

Example: confirmed

previous_order_statusstringcan be null

Example: not_processed

object (WebhookDataOrderPaymentStatusChanged)

order_idintegerrequired

Example: 1204551

order_numberintegercan be null

Example: 154

payment_statusstringrequired

Values:paidrefunded

Example: paid

sumnumber

Only for refunded

Example: 1250

object (WebhookDataFeedbackCreated)

feedback_idintegerrequired

Example: 40211

order_idintegercan be null

Example: 1204551

client_branch_profile_idintegercan be null

Example: 730112

textstringrequired

Example: Everything was hot and on time

statusstringrequired

Values:positivenegative

Example: positive

platformstringcan be null

Values:iosandroidsitevkapifb

Example: site

imagestringcan be null

Example: https://cdn.foodsoul.pro/zones/ru/branches/8412/images/feedback/3f2a.jpg

object (WebhookDataCourierAssigned)

order_idintegerrequired

Example: 1204551

order_numberintegercan be null

Example: 154

courier_idintegerrequired

Example: 5120

object (WebhookDataItemStopListChanged)

item.stop_list_changed — one event per each change; item parameter (size) identifiers

item_parameter_ids_addedarray of integerrequired

item_parameter_ids_removedarray of integerrequired

object (WebhookDataBranchWorkStatusChanged)

branch.work_status_changed — the branch has stopped or resumed accepting orders

blockedbooleanrequired

Example: true

noticestringcan be null

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

Example body

{
  "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"
  }
}

Your system's response

`2XX`	Accepted
`default`	Не принято, доставка повторяется