Webhooks
Webhooks are how Sous Chef pushes a state change to you as it happens. Every event also has a poll-able read behind it, so an integration with no reachable endpoint can still use the whole API. A webhook is a latency optimisation: the state it reports can also be read. Three order fields arrive on webhooks only: estimatedReadyAt, rejectReason and rejectReasonCode.
Destinations
An organization can have two webhook destinations:
newUrlis the destination you register yourself withsetAllWebhookSettings, together withnewUrlEvents, the list of events it receives. Every delivery to it is signed.newUrlEnabledpauses delivery without removing the registration. See the Settings section of the API Reference.legacyUrlis managed by Sous Chef for integrations set up before signed webhooks. It receives order events only, and you can pause it yourself withlegacyUrlEnabled. New integrations usenewUrl.
The API Reference has a page for each event, in the same section as the operations it belongs with: the order events under Orders, store.status.changed under Store status, item.availability.changed under Item availability, report.completed under Reports and menu.publication.completed under Menus. A page for an event documents its payload. It is not a separate endpoint. Every event in the catalogue below has a reference page.
Envelope
Every delivery is an HTTPS POST to your registered endpoint with a JSON body:
{
"id": "8c1d…",
"event": "order.created",
"timestamp": "2026-08-13T18:04:11.123Z",
"organization_id": "3f9c…",
"data": {}
}
idis the unique event id and your deduplication key. See Deduplication below.eventis the discriminator. Route on it, not on anything in the transport.timestampis the delivery time, not the event time. Order by the transported state (data.updatedAt,data.status/data.deliveryStatus), never by arrival.organization_idis your organization id: the same value you send asx-mealco-org-idon API requests. This one field is snake_case because it is a long-lived wire value.datacarries the changed object in the shape that the corresponding read returns, though not every field of it. An order event carries the order withoutstore,cancellationanddetails. A store-status event carries the part of the status that changed. Read the whole object withfetchOrderorfetchStoreStatuses.
Delivery semantics
| Property | Contract |
|---|---|
| Delivery | Retried, so duplicates happen. Make your handling idempotent. |
| Ordering | Not guaranteed. Order by the transported state, never by arrival. |
| Timeout | Respond within 30 seconds. Acknowledge first, process asynchronously. |
| Acknowledgement | Any 2xx. Anything else counts as a failed attempt. A redirect is not followed. |
| Retries | A failed attempt is retried up to four more times, 5 to 40 seconds apart, then not again. |
Deduplication
Deduplicate on the envelope's id, and on nothing else.
Every retry of one delivery carries the same id. Two legitimate transitions of one order are two events with two ids, so keying on id alone never collapses a real transition into a duplicate. Do not build a composite key out of the order id and the event type: those repeat across genuine transitions, and you would lose one. Note that timestamp is the moment an attempt was sent, so it differs between copies of one event and is not part of the key. newUrl and the legacy webhook feed assign their ids separately, so do not match an event across the two.
Recovery
The reads always hold the current state, so reconcile from them after an outage on your side: fetchOrders over the affected time window, and fetchStoreStatuses for the affected stores. Do not build an integration that can only learn state from webhooks. An endpoint that is down for an hour would then leave a permanent gap in your data rather than an hour of extra latency.
Event catalogue
| Event | Payload |
|---|---|
order.created | A new order entered Sous Chef from a connected platform. |
order.status.updated | Lifecycle transition (ready, finished). |
order.rejected | Rejection, including automatic rejections at intake, with the reason. |
order.cancelled | Cancellation: who cancelled (by), the reason and its code, and when. |
order.delivery.updated | Courier lifecycle: assigned, en route, completed, cancelled. |
store.status.changed | A store was paused or resumed, or a discrepancy with its platform appeared. |
item.availability.changed | Items were marked unavailable or restocked at a kitchen that sells them in your stores. |
report.completed | A requested report reached ready or failed. |
menu.publication.completed | Publication finished, with per-store, per-platform outcomes. |
order.cancelled is spelled with two ls, the same spelling as the order status value.
There are no discrepancy events
Discrepancy monitoring is state-based, not event-based. There is no store.discrepancy.detected event and no store.discrepancy.resolved event. A discrepancy is a standing condition, so you read it rather than receive it. Poll fetchStoreStatuses with hasDiscrepancy: true and route on the classification embedded in each status. The classification has four values (pauseNotPropagated, unexpectedPlatformPause, deactivatedByPlatform, unclassified). New values can be added, so route an unrecognised one like unclassified. Detection follows the reconciliation cadence. See Data freshness.
Choosing events
newUrlEvents selects the events that newUrl receives. Sending the list replaces the stored list, so an empty list means no events. The legacy webhook feed has no event list and carries order events only. Route on event in your handler, and answer 2xx to an event you do not recognise.
Securing your endpoint
Every delivery to newUrl is signed. It carries an X-SousChef-Signature header with a v2 signature: a JWT that you verify with a public key that you fetch from us. Hash the bytes as received, never a re-serialization of the parsed body. Verifying webhook signatures describes the scheme and has a Node example. Implement against that page.
Every delivery also carries the same values under X-OneTablet-Signature and X-OneTablet-Timestamp, for backward compatibility.