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 → DELIVERED.

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.
DELIVERED	The delivery has been completed. The rider has taken the delivery cargo to the dropoff point.
PARTIALLY_DELIVERED	This status is only relevant for deliveries where multiple riders are needed. The delivery is partially complete when some riders have completed their delivery, while others failed. A reason code will be provided.
CANCELLED	The delivery has been cancelled by the rider or the customer.
UNFULFILLED	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 DELIVERED 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 UNFULFILLED event.
When a delivery has been partially delivered, you will receive a PARTIALLY_DELIVERED event.

Failures

Retry Logic

Deliveroo will retry the request for up to 10 minutes.