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",
    "rider_contact_number": "+447700900000",
    "verification": {
        "type": "CODE",
        "value": "45"
    },
    "return_verifications": [
        {
            "type": "CODE",
            "value": "13"
        }
    ],
    "status": {
      "effective_at": "2024-07-10T11:23:09Z",
      "status": "ACTIVE"
    }
  }
}

The rider_contact_number is a phone number the customer can use to contact the rider for this delivery. It is a single number shared across all deliveries in a market — Deliveroo's call-masking layer connects the customer to the rider handling their delivery, and neither party sees the other's real number. For larger orders that involve more than one rider, the same number is used and the call-masking layer connects the customer to a rider on their delivery. The number becomes reachable once the rider has picked up the order and remains active until the delivery is completed; calls before pickup or after the delivery has finished will not connect. It may be absent for markets where it is not configured.

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.