Skip to main content

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_categorydelivery.statusdelivery.dasher_statusevent_data
delivery_createdscheduledunassigned
dasher_confirmedassignedaccepted
enroute_to_pickup
driver_batchedassigned
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_pickupassignedenroute_to_pickup
dasher_confirmed_store_arrivalassignedarrived_at_store
dasher_picked_uppicked_uppicked_up
enroute_to_dropoff
dasher_enroute_to_dropoffpicked_upenroute_to_dropoff
dasher_confirmed_consumer_arrivalpicked_uparrived_at_consumer
dasher_dropped_offdelivereddropped_off
delivery_abandonedcould_not_delivercould_not_deliverreason
delivery_pending_returnpending_returnpending_return
dasher_enroute_to_returnpending_returnenroute_to_return
dasher_confirmed_return_arrivalpending_returnarrived_at_return
dasher_dropped_off_returnreturneddropped_off_return
delivery_cancelledcancelledunassignedreason
delivery_attemptedcould_not_delivercould_not_deliver
dasher_supplied_parking_detailsassignedarrived_at_store
delivery_post_tip_receiveddelivereddropped_offpost_tip_amount
post_tip_received_time
delivery_refundedall statuses applicableall statuses applicablereason
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.

ReasonDescription
cancel_by_dispatchOrder was cancelled by DoorDash support
cancel_by_merchantThe order was cancelled by the merchant
cancel_by_order_placerThe order was cancelled by the person that created it
customer_requested_otherThe customer cancelled the order
dasher_cannot_fulfill_otherThe Dasher couldn't fulfill the order
dasher_not_respondingThe Dasher was not responding
drive_order_picked_up_by_customerThe order was picked up by the customer
duplicate_orderThe order is a duplicate of another order
fraudulent_orderDoorDash suspects this order is fraudulent
items_temp_unavailableItems were temporarily unavailable
no_available_dashersNo Dashers are available for this order
nontablet_protocol_issueDoorDash didn't receive the full order
otherDoorDash encountered an unknown error
picked_up_by_other_dasherOrder was picked up by another dasher
store_cannot_fulfill_otherThe store couldn't fulfill the order
store_closedThe store is not available at the time the order is requested or was closed when the Dasher arrived
test_orderThe order was a test order and was cancelled by a clean-up job
too_busyThe restaurant is too busy
too_lateThe order was taking too long
wrong_delivery_addressThe delivery address was incorrect
package_needs_redeliveryThe package delivery attempt failed and will be redelivered
package_never_receivedThe package was never received at dashmart
package_lost_at_facilityThe package was lost after receiving at dashmart

Refund reasonsโ€‹

Reason and reason_comments are sent as string

ReasonDescription
canceled_order_by_doordashOrder canceled by DoorDash
canceled_order_by_merchant_requestOrder canceled by merchant
canceled_order_by_customer_requestOrder canceled by customer
delivered_lateOrder delivered late
delivered_earlyOrder delivered early
never_deliveredOrder did not arrive
missing_or_incorrect_itemsOrder has missing or incorrect items
poor_food_qualityPoor food quality
delivery_qualityDelivery quality does not match customer expectation
health_safety_concernDelivery quality does not match customer expectation
adjust_tipCustomer adjusted tip
special_instructions_not_followedSpecial instructions were not followed
otherOther

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.

ReasonDescription
cash_cx_short_on_cashCustomer was short on cash
cash_dx_mismatch_changeDasher did not have sufficient change
cash_cx_unavailableCustomer unavailable
cash_cx_refuses_paymentCustomer refused to pay
otherOther

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โ€‹