Webhooks for deliveries
Webhooks enable near-real-time information flow from DoorDash and our Dashers to your application and your customers. With webhooks, you can enable real-time scenarios like a map view showing your customers how far away their Dasher is, push notifications telling your customers the latest status of their order, and much more. DoorDash strongly recommends integrating with webhooks to provide real time updates to the customer and ensure the best in class delivery experience.
API: Drive
This doc covers the Drive API. If you're using the Drive (classic) API, see the reference guide for Drive (classic) webhooks.
Events​
All deliveries​
DoorDash Developer sends webhooks for the following events, as soon as the event takes place:
DASHER_CONFIRMED: A Dasher has accepted your delivery and is on the way to the pickup location.DASHER_CONFIRMED_PICKUP_ARRIVAL: The Dasher has confirmed that they arrived at the pickup location and are attempting to pick up the delivery.DASHER_PICKED_UP: The Dasher has picked up the delivery.DASHER_CONFIRMED_DROPOFF_ARRIVAL: The Dasher has confirmed that they arrived at the dropoff location.DASHER_DROPPED_OFF: The Dasher has dropped off the delivery at the dropoff location and the delivery is complete.DELIVERY_CANCELLED: The delivery has been cancelled.
Return-to-pickup deliveries only​
Deliveries that can be returned-to-pickup may generate webhooks for the following events:
DELIVERY_RETURN_INITIALIZED: The Dasher was unable to deliver your delivery to the dropoff location; they contacted support to arrange a return-to-pickup delivery and are returning to the pickup location.DASHER_CONFIRMED_RETURN_ARRIVAL: The Dasher has confirmed that they arrived at the pickup location and are attempting to return the delivery.DELIVERY_RETURNED: The delivery has been returned successfully.DELIVERY_CANCELLED(withreason=failed_to_return): The delivery was unable to be returned.
Delivery tracking​
You can also enable various dasher_enroute... webhooks that send the location of Dasher every 30 seconds, starting 15 mins before pickup or dropoff.
To use these webhooks, submit a support request asking that they be enabled for your integration.
dasher_enroute_to_pickup: The Dasher is on their way to pick up the delivery.dasher_enroute_to_dropoff: The Dasher is on their way to the dropoff location.dasher_enroute_to_return: The Dasher is on their way back to the pick up location to return the items.
Fields​
Webhooks contain all of the details about a delivery that are available when the webhook is sent. If a field is empty or not available, the field is not sent in the webhook body. For example, pickup_time_actual is not included in webhook payloads until the delivery has been picked up by the Dasher. Your code should always check if a field is present before accessing it.
| Field name | Description | field available in webhook event |
|---|---|---|
cancellation_reason | Why the order was cancelled | Only the DELIVERY_CANCELLED event |
cancellation_reason_message | Why the order was cancelled, in the Dasher's words | Only the DELIVERY_CANCELLED event and only if cancellation_reason=failed_to_return |
contactless | Whether the delivery was contactless or normal | All events |
created_at | When the webhook was created | All events |
currency | The currency of order_value, fee, and tip in cents (see list below) | All events |
dasher_id | The unique identifier for the Dasher; example: 123212. | All events |
dasher_name | The first name and last initial of the Dasher delivering the order; example: John D. | All events |
dasher_phone_number DEPRECATED | This field has been replaced by dasher_dropoff_phone_number | All events |
dasher_dropoff_phone_number | The phone number of the dasher for the dropoff contact to use; number is masked for privacy | All events |
dasher_pickup_phone_number | The phone number of the dasher for the pickup contact to use; number is masked for privacy | All events |
dasher_location | Latitude and longitude of the dasher. | All events |
dasher_vehicle_make | Make of the dasher's vehicle | All events |
dasher_vehicle_model | Model of the dasher's vehicle | All events |
dasher_vehicle_year | Year of the dasher's vehicle | All events |
dropoff_address | Where the delivery will be dropped off | All events |
dropoff_contact_family_name | Family name of the contact. | All events |
dropoff_contact_given_name | Given name of the contact. | All events |
dropoff_contact_send_notifications | Whether the contact will receive notifications from DoorDash for this delivery; default is false | All events |
dropoff_instructions | Instructions for the Dasher to follow when dropping off the order | All events |
dropoff_phone_number | The phone number for the Dasher to call in case of problems with pickup | All events |
dropoff_time_actual | When the delivery was dropped off | All events after and including DASHER_DROPPED_OFF |
dropoff_time_estimated | When the delivery is estimated to be dropped off | All events |
dropoff_verification_image_url | The verification image taken by the Dasher when the order was dropped off | All events after and including DASHER_DROPPED_OFF |
dropoff_signature_image_url | The signature image obtained from customer when the order was dropped off if applicable. | All events after and including DASHER_DROPPED_OFF |
event_name | The event that triggered the webhook (see list above) | All events |
external_delivery_id | The ID provided when the delivery was created | All events |
fee | The delivery feeds charged by DoorDash | All events |
order_value | The value of all the items in the order | All events |
pickup_address | Where the delivery will be picked up | All events |
pickup_instructions | Instructions for the Dasher to follow when picking up the order | All events |
pickup_phone_number | The phone number for the Dasher to call in case of problems with pickup | All events |
pickup_reference_tag | A piece of information that can help the Dasher identify the correct delivery item to pick up | All events |
pickup_external_business_id | The string identifier used to create your business. Used in combination with pickup_external_store_id to select the pick up location | All events |
pickup_external_store_id | The string identifier used to create your store | All events |
pickup_verified_timestamp | The timestamp when the pickup verification is done by dasher. Sent only if feature is enabled. | Only the DASHER_PICKED_UP event |
updated_at | Timestamp when the delivery info was updated. | All events |
pickup_time_actual | When the delivery was picked up | All events after and including DASHER_PICKED_UP |
pickup_time_estimated | When the delivery is estimated to be picked up | All events |
pickup_verification_image_url | The verification image taken by the Dasher when the order was picked up; only sent for peer-to-peer orders | All events after and including DASHER_PICKED_UP |
return_address | Where the delivery will be returned | All events after and including DELIVERY_RETURN_INITIALIZED |
return_time_actual | When the delivery was returned to the pickup location | Only the DELIVERY_RETURNED event |
return_time_estimated | When the delivery is estimated to be returned to the pickup location | All events after and including DELIVERY_RETURN_INITIALIZED |
support_reference | An identifer you can use if talking to DoorDash support about this order | All events |
tip | The amount to tip the Dasher | All events |
tracking_url | The DoorDash Merchant Portal URL that you can use to track the delivery | All events |
Cancellation reasons​
Use this table to learn more about the cancellation reason you received in your API response or webhook.
| Reason | Description |
|---|---|
| cancel_by_dispatch | Order was cancelled by DoorDash support |
| cancel_by_merchant | The order was cancelled by the merchant |
| cancel_by_order_placer | The order was cancelled by the person that created it |
| customer_requested_other | The customer cancelled the order |
| dasher_cannot_fulfill_other | The Dasher couldn't fulfill the order |
| dasher_not_responding | The Dasher was not responding |
| drive_order_picked_up_by_customer | The order was picked up by the customer |
| duplicate_order | The order is a duplicate of another order |
| fraudulent_order | DoorDash suspects this order is fraudulent |
| items_temp_unavailable | Items were temporarily unavailable |
| no_available_dashers | No Dashers are available for this order |
| nontablet_protocol_issue | DoorDash didn't receive the full order |
| other | DoorDash encountered an unknown error |
| picked_up_by_other_dasher | Order was picked up by another dasher |
| store_cannot_fulfill_other | The store couldn't fulfill the order |
| store_closed | The store is not available at the time the order is requested or was closed when the Dasher arrived |
| test_order | The order was a test order and was cancelled by a clean-up job |
| too_busy | The restaurant is too busy |
| too_late | The order was taking too long |
| wrong_delivery_address | The delivery address was incorrect |
| package_needs_redelivery | The package delivery attempt failed and will be redelivered |
| package_never_received | The package was never received at dashmart |
| package_lost_at_facility | The package was lost after receiving at dashmart |
Data formats​
All ..._time_... fields are sent as ISO-8601 date and times and are therefore sent in the UTC time zone.
Retries​
DoorDash sends each webhook event up to 3 times. In other words, when DoorDash sends a webhook, if we receive a response other than 200 OK or no response at all, we try to send it 2 more times.
Example webhook payload​
{
"created_at": "2022-02-01T23:18:22.791883Z",
"event_name": "DASHER_DROPPED_OFF",
"external_delivery_id": "c19a5d37-e457-4247-9a67-921ec0134125",
"dasher_id": 123212,
"dasher_name": "John D.",
"dasher_dropoff_phone_number": "+16504379788",
"dasher_pickup_phone_number": "+16504379799",
"dasher_location": {"lat": 43.333333333, "lng": -79.333333333},
"dasher_vehicle_make": "Honda",
"dasher_vehicle_model": "Civic",
"dasher_vehicle_year": "2003",
"pickup_address": "1000 4th Avenue, Seattle, WA 98104",
"pickup_phone_number": "+1(855)9731040",
"pickup_instructions": "please take it to floor 21",
"pickup_reference_tag": "reftag",
"pickup_external_business_id": "ase-243-dzs",
"pickup_external_store_id": "ase-243-dzs",
"dropoff_address": "1201 3rd Avenue, Seattle, WA 98101",
"dropoff_phone_number": "+1(855)9731040",
"dropoff_instructions": "please take it to floor 21",
"dropoff_contact_given_name": "John",
"dropoff_contact_family_name": "Doe",
"dropoff_contact_send_notifications": true,
"order_value": 5555,
"currency": "USD",
"updated_at": "2022-02-01T23:18:22.791883Z",
"pickup_time_estimated": "2022-02-01T23:32:06.000000Z",
"pickup_time_actual": "2022-02-01T23:17:20.521249Z",
"dropoff_time_estimated": "2022-02-01T23:56:06.000000Z",
"dropoff_time_actual": "2022-02-01T23:18:22.541773Z",
"fee": 975,
"tip": 230,
"support_reference": "1343593362",
"tracking_url": "https://doordash.com/drive/portal/track/53904a0b-18cd-4308-b6dc-1d83932d7990",
"contactless": false
}