Webhook

Order status callback

The Order status notification webhook will be called from Deliveroo when an order is created in Deliveroo. This webhook is triggered on the following events during the order lifecycle:

StatusDescription
PLACEDThe order was created.
ACCEPTEDThe partner accepted the order.
REJECTEDThe partner rejected the order.
CANCELEDThe partner cancelled the order.

Please notice that while every attempt is made to make callbacks in the order they occurred and in a timely manner, neither can be absolutely guaranteed. It is also possible to receive the same callback more than once.

Ordering and deduplication

Webhooks are processed asynchronously. Each distinct status change triggers a separate webhook — events are never collapsed or merged, even when multiple status transitions occur in rapid succession.

Deduplication: If a status has already been recorded for an order, a duplicate status change will not trigger an additional webhook. Each status can only appear once in an order's lifecycle.

Guaranteed ACCEPTED delivery: If an order transitions past ACCEPTED (e.g., directly to a rider status like IN_TRANSIT) without an explicit ACCEPTED event, the system will detect this gap and synthesize an ACCEPTED webhook. In this case:

  • The webhook status field will be set to ACCEPTED.
  • A synthetic ACCEPTED entry will be appended to the status_log array in the payload.

This ensures partners always receive the ACCEPTED status callback, even when the underlying order lifecycle skips it due to auto-completion or rapid state progression.

Using status_log for reconciliation: Each webhook payload includes a status_log array containing the full history of status changes for the order, sorted by timestamp. Partners can use this field to reconcile their local state and detect any events that may have been missed due to transient delivery failures.

Payload

Check webhook receiver example to get insight into payload sent by Deliveroo.

Configuration

The Picking API Order status webhook can be configured either at the integrator level, to receive statuses for all partners, or it can be configured at the partner level, to have per-partner webhook URLs. Only one of these options can be used.

Authentication

Upon registration, your account manager will provide you with a webhook-secret. This secret value will differ from the api-secret from your credentials. The webhook secret and a sequential globally unique identifier (GUID) are used to generate a Hash-based message authentication code (HMAC) of the order payload.

When you receive a POST webhook request, you will be able to compute a digest and verify that it’s a genuine, authorized request sent from Deliveroo.

Delivery failure and retries

A successful webhook callback occurs when the server responds with an HTTP 2xx success range; any other HTTP status or a timeout will result in a retry.

Our servers will retry failed webhook callbacks applying exponential back-off delays and circuit breaking when failures are successive in a short amount of time.

When the circuit breaker is tripped, the total number of requests per minute is significantly reduced until the endpoint appears healthy again.

For order statuses, we "give up" and discard the event callback after 30 minutes.


Did this page help you?