Listening for Delivery Events

Once you have configured the Delivery Events webhook, Deliveroo will begin notifying your integration about delivery-related events

The Delivery Events webhook is meant to be informational. How you process the information provided through this webhook depends on your requirements.

A typical delivery status lifecycle is REQUESTED → ACTIVE → COMPLETED.

Keep in mind 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. The effective_at field in the status object should be used to derive the event ordering.

Example payload of webhook:

{
  "event": "delivery.update_status",
  "body": {
    "delivery_id": "f7e458ec-3d8e-4271-9a25-34d2fa125782",
    "external_ref_id": "6823e970-283d-4bfd-849e-7bcb0e4a1b40#courier",
    "verification": {
        "type": "CODE",
        "value": "4532"
    }
    "status": {
      "effective_at": "2024-07-10T11:23:09Z",
      "status": "ACTIVE"
    }
  }
}

Delivery Statuses

Delivery Status	Description
REQUESTED	Deliveroo has received a delivery request and is working on assigning a rider.
ACTIVE	A rider has been assigned and the delivery is under way.
COMPLETED	The delivery has been completed. The rider has taken the delivery cargo to the dropoff point.
CANCELLED	The delivery has been cancelled by the rider or the customer.
FAILED	The delivery has failed. A reason code will be provided.

How do Delivery Events Work?

Deliveroo sends you a notification via Delivery Events webhook (delivery.status_update) every time an event related to the delivery occurs:

When a delivery has been requested for a given cargo, you will receive a REQUESTED event.
You will receive a ACTIVE event when a rider has been assigned to the delivery.
You will receive a COMPLETED when the rider has successfully delivered the cargo to the dropoff location.
When a delivery has been cancelled, you will receive a CANCELLED event.
When a delivery has failed, you will receive a FAILED event.

Failures

Retry Logic

Deliveroo will retry the request for up to 10 minutes.