API docs
Sous Chef Management API
Request access

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:

  • newUrl is the destination you register yourself with setAllWebhookSettings, together with newUrlEvents, the list of events it receives. Every delivery to it is signed. newUrlEnabled pauses delivery without removing the registration. See the Settings section of the API Reference.
  • legacyUrl is managed by Sous Chef for integrations set up before signed webhooks. It receives order events only, and you can pause it yourself with legacyUrlEnabled. New integrations use newUrl.

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": {}
}
  • id is the unique event id and your deduplication key. See Deduplication below.
  • event is the discriminator. Route on it, not on anything in the transport.
  • timestamp is the delivery time, not the event time. Order by the transported state (data.updatedAt, data.status / data.deliveryStatus), never by arrival.
  • organization_id is your organization id: the same value you send as x-mealco-org-id on API requests. This one field is snake_case because it is a long-lived wire value.
  • data carries the changed object in the shape that the corresponding read returns, though not every field of it. An order event carries the order without store, cancellation and details. A store-status event carries the part of the status that changed. Read the whole object with fetchOrder or fetchStoreStatuses.

Delivery semantics

PropertyContract
DeliveryRetried, so duplicates happen. Make your handling idempotent.
OrderingNot guaranteed. Order by the transported state, never by arrival.
TimeoutRespond within 30 seconds. Acknowledge first, process asynchronously.
AcknowledgementAny 2xx. Anything else counts as a failed attempt. A redirect is not followed.
RetriesA 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

EventPayload
order.createdA new order entered Sous Chef from a connected platform.
order.status.updatedLifecycle transition (ready, finished).
order.rejectedRejection, including automatic rejections at intake, with the reason.
order.cancelledCancellation: who cancelled (by), the reason and its code, and when.
order.delivery.updatedCourier lifecycle: assigned, en route, completed, cancelled.
store.status.changedA store was paused or resumed, or a discrepancy with its platform appeared.
item.availability.changedItems were marked unavailable or restocked at a kitchen that sells them in your stores.
report.completedA requested report reached ready or failed.
menu.publication.completedPublication 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.