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.
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 |
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 | Reason Comments |
|---|---|
| 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
}