Listening for Rider Events

Rider events

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

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

Update Status event

A typical rider status lifecycle is EN_ROUTE_TO_SITE → ARRIVED_AT_SITE → CONFIRMED_AT_SITE -> EN_ROUTE_TO_CUSTOMER -> ARRIVED_AT_CUSTOMER -> CONFIRMED_AT_CUSTOMER -> COMPLETED_DELIVERY.

Please note that several riders can be assigned to a delivery if it's too big for one to fulfill. You can expect to see repeated statuses in those cases.

Event payload

{
  "event": "riders.update_status",
  "body": {
    "delivery_id": "f7e458ec-3d8e-4271-9a25-34d2fa125782",
    "external_ref_id": "6823e970-283d-4bfd-849e-7bcb0e4a1b40#courier",
    "riders": [
		{
			"rider_id": "4d50561f-2950-44e3-af7a-f7c60a6a014e"
			"status": {
			    "effective_at": "2024-01-01T08:00:00.52Z",
			    "status": "EN_ROUTE_TO_SITE"
			}
		},
		{
			"rider_id": "47cd3007-4723-4b25-ae76-b7e614078aa5"
			"status": {
			    "effective_at": "2024-01-01T08:05:00.52Z",
			    "status": "CONFIRMED_AT_SITE"
			}
		},
		{
			"rider_id": "47cd3007-4723-4b25-ae76-b7e614078aa6"
			"status": {
			    "effective_at": "2024-01-01T08:05:00.52Z",
			    "status": "FAILED_DELIVERY",
			    "reason": "BAD_WEATHER"
			}
		}
	]
  }
}

Rider Statuses

Rider Status	Description
EN_ROUTE_TO_SITE	The rider has accepted the delivery and is en route to the site.
ARRIVED_AT_SITE	The rider is nearing the site.
CONFIRMED_AT_SITE	The rider has reached the site, confirmed on the Rider App.
EN_ROUTE_TO_CUSTOMER	The rider is en route to the customer location.
ARRIVED_AT_CUSTOMER	The rider is nearing the customer location.
CONFIRMED_AT_CUSTOMER	The rider has reached the customer, confirmed on the Rider App.
COMPLETED_DELIVERY	The rider has completed the delivery.
FAILED_DELIVERY	The rider has failed to deliver the cargo. A reason will be provided when available.

How do Rider Events Work?

Deliveroo sends you a notification via Rider Events webhook (riders.update_status) every time an event related to the
rider for a given delivery occurs:

When a rider has accepted the delivery and is on their way to the site, you will receive a EN_ROUTE_TO_SITE event.
You will receive a ARRIVED_AT_SITE event when a rider is close to a site.
You will receive a CONFIRMED_AT_SITE when the rider confirms to be at the site on the Rider App.
When a rider has picked up the cargo from the site and is on their way to the customer, you will receive a EN_ROUTE_TO_CUSTOMER event.
You will receive a ARRIVED_AT_CUSTOMER event when a rider is close to the customer's location.
You will receive a CONFIRMED_AT_CUSTOMER event when a rider has arrived to the customer's location.
7a. You will receive a COMPLETED_DELIVERY event when a rider has successfully delivered the cargo to the customer.
7b. You will receive a FAILED_DELIVERY event if a rider has failed to deliver the cargo to the customer.

Rider geolocation

When one of riders geolocation will change significantly (more than 1 meter) you will receive riders.update_location event. You should not expect to receive this event more often than every 10 seconds. However, if we do not detect movement of riders we will skip sending notification.

Event payload

{
    "event": "riders.update_location",
    "body":
    {
        "delivery_id": "114f8ca5-dbea-49f3-8cd5-e340f80adbd2",
        "external_ref_id": "e7311dbc-9650-47d6-94cd-f2915afda001",
        "riders":
        [
            {
                "location":
                {
                    "effective_at": "2024-10-17T09:50:41.831018004Z",
                    "lat": 51.06191635131836,
                    "lon": -1.315000057220459
                },
                "rider_id": "c70f8a79-af33-4035-ae51-3687970a2e6e"
            }
        ]
    }
}

Failures

Retry Logic

Deliveroo will retry the request for up to 10 minutes.