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:
| Status | Description |
|---|---|
| PLACED | The order was created. |
| ACCEPTED | The partner accepted the order. |
| REJECTED | The partner rejected the order. |
| CANCELED | The 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
statusfield will be set toACCEPTED. - A synthetic
ACCEPTEDentry will be appended to thestatus_logarray 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.
Updated 16 days ago
