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 (classic)
This doc covers the Drive (classic) API. If you're using the Drive API, see the reference guide for Drive webhooks.
Events
DoorDash Developer sends webhooks for the following events, as soon as the event takes place:
delivery_created: When a delivery is created.dasher_confirmed: The Dasher confirmed to do the delivery.driver_batched: The Dasher has been assigned another order in addition to this current order.dasher_confirmed_store_arrival: The Dasher confirmed they have arrived at the pick up location.dasher_picked_up: The Dasher has picked up the delivery items.dasher_confirmed_consumer_arrival: The Dasher confirmed they have arrived at the drop off location.dasher_dropped_off: The Dasher had dropped off the delivery at destination.delivery_cancelled: The delivery has been cancelled.delivery_pending_return: A return has been initiated for this delivery.dasher_confirmed_return_arrival: The Dasher has arrived at the return location.dasher_dropped_off_return: The Dasher has dropped off the return delivery.return_delivery_cancelled: The return delivery was cancelled.delivery_attempted: The Dasher has tried to make contact with the customer, the customer was unavailable to meet the Dasher.
Some additional events are sent if they're enabled for your business:
dasher_supplied_parking_details: Parking details supplied by the Dasher when at the store, to pick up an order or drop off a return.delivery_post_tip_received: Post tip received for the delivery.delivery_refunded: Order has been refunded. Refund amount specified in payload.delivery_abandoned: The Dasher was unable to finish the delivery at destination, delivery was abandoned. This event is only available for Cash on Delivery.
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.
DoorDash sends the enroute webhook events every 30 seconds, starting 15 mins before pickup or dropoff.
caution
Not all events are dispatched for deliveries created via the Delivery Simulator. Please refer to the section on Delivery Simulator for more detail.
Mapping webhooks to delivery statuses
| Webhook event_category | delivery.status | delivery.dasher_status | event_data |
|---|---|---|---|
| delivery_created | scheduled | unassigned | |
| dasher_confirmed | assigned | accepted enroute_to_pickup | |
| driver_batched | assigned picked_up delivered pending_return | accepted enroute_to_pickup arrived_at_store picked_up enroute_to_dropoff arrived_at_consumer dropped_off enroute_to_return arrived_at_return | |
| dasher_enroute_to_pickup | assigned | enroute_to_pickup | |
| dasher_confirmed_store_arrival | assigned | arrived_at_store | |
| dasher_picked_up | picked_up | picked_up enroute_to_dropoff | |
| dasher_enroute_to_dropoff | picked_up | enroute_to_dropoff | |
| dasher_confirmed_consumer_arrival | picked_up | arrived_at_consumer | |
| dasher_dropped_off | delivered | dropped_off | |
| delivery_abandoned | could_not_deliver | could_not_deliver | reason |
| delivery_pending_return | pending_return | pending_return | |
| dasher_enroute_to_return | pending_return | enroute_to_return | |
| dasher_confirmed_return_arrival | pending_return | arrived_at_return | |
| dasher_dropped_off_return | returned | dropped_off_return | |
| delivery_cancelled | cancelled | unassigned | reason |
| delivery_attempted | could_not_deliver | could_not_deliver | |
| dasher_supplied_parking_details | assigned | arrived_at_store | |
| delivery_post_tip_received | delivered | dropped_off | post_tip_amount post_tip_received_time |
| delivery_refunded | all statuses applicable | all statuses applicable | reason amount currency code amount details |
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 |
Refund reasons
Reason and reason_comments are sent as string
| Reason | Description |
|---|---|
| canceled_order_by_doordash | Order canceled by DoorDash |
| canceled_order_by_merchant_request | Order canceled by merchant |
| canceled_order_by_customer_request | Order canceled by customer |
| delivered_late | Order delivered late |
| delivered_early | Order delivered early |
| never_delivered | Order did not arrive |
| missing_or_incorrect_items | Order has missing or incorrect items |
| poor_food_quality | Poor food quality |
| delivery_quality | Delivery quality does not match customer expectation |
| health_safety_concern | Delivery quality does not match customer expectation |
| adjust_tip | Customer adjusted tip |
| special_instructions_not_followed | Special instructions were not followed |
| other | Other |
Abandonment reasons
Use this table to learn more about the abandonment reason you received in your API response or webhook. Note: this event is only available for Cash on Delivery.
| Reason | Description |
|---|---|
| cash_cx_short_on_cash | Customer was short on cash |
| cash_dx_mismatch_change | Dasher did not have sufficient change |
| cash_cx_unavailable | Customer unavailable |
| cash_cx_refuses_payment | Customer refused to pay |
| other | Other |
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 payload
{
"event_category": "dasher_dropped_off",
"delivery": {
"id": 34290434,
"status": "delivered",
"dasher_status": "dropped_off",
"driver_reference_tag": "ff8b6480-8b07-4eda-9a5f-209044884a6d",
"quoted_delivery_time": "2018-01-17T19:57:07Z",
"fee": 0,
"rating": null,
"pickup_window_start_time": "2018-01-17T20:45:00.000000Z",
"actual_pickup_time": "2018-01-17T20:50:04.918981Z",
"quoted_pickup_time": "2018-01-17T19:42:07Z",
"estimated_pickup_time": "2018-01-03T23:23:05Z",
"dropoff_address": {
"city": "Fremont",
"state": "CA",
"street": "43514 Christy Street",
"unit": "",
"zip_code": "94538",
"dasher_parking_details": "Parking Stall 1234"
},
"external_delivery_id": null,
"actual_delivery_time": "2018-01-17T20:50:43.380171Z",
"actual_return_time": "2018-01-17T21:02:43.380171Z",
"delivery_verification_image_url": "imageurl/image.jpg",
"delivery_window_start_time": null,
"return_delivery_id": null,
"parent_delivery_id": null,
"items": [],
"cash_on_delivery": null,
"route_id": null,
"quantity": 1,
"pickup_window_end_time": null,
"submit_platform": "drive_api",
"store_point": null,
"delivery_window_end_time": null,
"barcode_scanning_required": false,
"tip": 0,
"order_volume": 3,
"allow_unattended_delivery": true,
"contains_alcohol": false,
"signature_required": false,
"signature_image_url": null,
"delivery_tracking_url": null,
"updated_at": "2018-01-17T20:49:33.442377Z",
"team_lift_required": false,
"external_store_id": "8685",
"is_return_delivery": false,
"batch_id": null,
"estimated_return_time": null,
"currency": "USD",
"dropoff_instructions": "Dropoff instructions",
"pickup_address": {
"city": "Palo Alto",
"state": "CA",
"street": "470 Olive Ave",
"unit": "",
"zip_code": "",
"dasher_parking_details": "Parking Stall 4567",
},
"dasher": {
"phone_number": "+16505555555",
"first_name": "Ada",
"last_name": "Lovelace",
"id": 7897789,
"profile_image_url": null,
"dasher_phone_number_for_customer": "+16505555556",
"vehicle": {
"license_plate_number": "",
"color": "",
"make": "Toyota",
"model": "Corolla",
"year": "2006"
},
"location": {
"lat": 123.45,
"lng": -37.91
}
},
"order_value": 199,
"pickup_instructions": "Pickup instructions",
"customer": {
"phone_number": "+16505555555",
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]"
}
},
"created_at": "2018-05-03T22:11:17.042353Z",
"event_data": {
"reason": "delivered_late",
"reason_comments": "Order delivered late"
}
}
Next steps
- Visit the webhooks for refunds reference