Webhooks for parcel orders

Webhooks enable near-real-time information flow from DoorDash and our drivers 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 driver 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 parcels

DoorDash Developer sends webhooks for the following events, as soon as the event takes place:

PARCEL_LABELED: The first time a parcel with this barcode is created in the DoorDash system
PARCEL_SCANNED: The first time the parcel is received at its destination facility
DASHER_PICKED_UP: A delivery driver has scanned and confirmed pickup of this package.
DASHER_CONFIRMED_DROPOFF_ARRIVAL: The driver has confirmed that they arrived at the dropoff location.
DASHER_DROPPED_OFF: The driver has dropped off the delivery at the dropoff location and the delivery is complete.

Parcels with mid-mile hops

For parcels that arrive and depart mid mile facilities along the way to a destination facility, these events are fired for each mid-mile facility:

PARCEL_ORIGIN_ARRIVED: When a driver arrives at the merchant's origin facility for pickup.
PARCEL_ORIGIN_PICKED_UP: When the parcel has left the merchant's origin facility, confirmed by a scan.
PARCEL_MID_MILE_ARRIVED: The first time a parcel has arrived at a DashLink regional facility, confirmed by a scan.
PARCEL_MID_MILE_DEPARTED: When the parcel has left its current regional facility and on the way to the next facility.

Parcels with failed delivery attempts

A parcel delivery attempt may not always be successful, in which case the driver may choose to try again or return to the DoorDash facility. When parcels are received back at the facility after a failed attempt, they may have another delivery attempt scheduled or be sent back to merchant if it is undeliverable. These parcels may generate the following events:

DASHER_ATTEMPTED_DELIVERY: The driver was unable to deliver your delivery to the dropoff location.
PARCEL_RECEIVED_TO_REDELIVER: The package was received back at the facility and will be attempted again shortly.
PARCEL_RETURN_TO_MERCHANT: The package was received at the facility and being returned to merchant.

Webhooks DASHER_ATTEMPTED_DELIVERY, PARCEL_RECEIVED_TO_REDELIVER, and PARCEL_RETURN_TO_MERCHANT contain either a return_reason or undeliverable_reason_code indicating why the delivery attempt failed.

Only PARCEL_RETURN_TO_MERCHANT and PARCEL_LOST_IN_TRANSIT should be considered a terminal undeliverable state, where a customer refund can be issued.

Parcels with exception statuses

A parcel delivery may also be in an exception status state, in which the following events detail the exception state at that point:

PARCEL_DELAYED: The package was delayed after being scanned at a DashLink facility.
PARCEL_AWAITING: The package was delayed before being scanned at DashLink facility, for example if it was not shipped on time to DashLink by the origin warehouse.
PARCEL_LOST_IN_TRANSIT: The package was lost after being received at a DashLink facility.

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
`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 driver; example: 123212.	All events
`dasher_name`	The first name and last initial of the driver delivering the order; example: John D.	All events
`dasher_dropoff_phone_number`	The phone number of the driver for the dropoff contact to use; number is masked for privacy	All events
`dasher_pickup_phone_number`	The phone number of the driver for the pickup contact to use; number is masked for privacy	All events
`dasher_location`	Latitude and longitude of the driver.	All events
`dasher_vehicle_make`	Make of the driver's vehicle	All events
`dasher_vehicle_model`	Model of the driver's vehicle	All events
`dasher_vehicle_year`	Year of the driver'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 driver to follow when dropping off the order	All events
`dropoff_phone_number`	The phone number for the driver 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 driver 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
`parcel_awaiting_reason`	Why the delivery was delayed before being scanned at a DashLink facility	Only the `PARCEL_AWAITING` event
`parcel_delayed_reason`	Why the delivery was delayed after being scanned at a DashLink facility	Only the `PARCEL_DELAYED` event
`pickup_address`	Where the delivery will be picked up	All events
`pickup_instructions`	Instructions for the driver to follow when picking up the order	All events
`pickup_phone_number`	The phone number for the driver to call in case of problems with pickup	All events
`pickup_reference_tag`	A piece of information that can help the driver identify the correct delivery item to pick up	All events Use this field to link together the original order + redelivery attempts
`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_time_actual`	When the delivery was picked up	All events after and including `DASHER_DROPPED_OFF`
`pickup_time_estimated`	When the delivery is estimated to be picked up	All events
`pickup_verification_image_url`	The verification image taken by the driver when the order was picked up; only sent for peer-to-peer orders	All events after and including `DASHER_DROPPED_OFF`
`return_reason`	Why the delivery attempt was unsuccessful	Only the `PARCEL_RECEIVED_TO_REDELIVER`, `PARCEL_RETURN_TO_MERCHANT` events
`support_reference`	An identifer you can use if talking to DoorDash support about this order	All events
`tip`	The amount to tip the driver	All events
`tracking_url`	The DoorDash Merchant Portal URL that you can use to track the delivery	All events
`undeliverable_reason_additional_details`	Additional details provided by the driver on why the delivery attempt was unsuccesful	Only the `DASHER_ATTEMPTED_DELIVERY` event
`undeliverable_reason_code`	Why the delivery attempt was unsuccessful	Only the `DASHER_ATTEMPTED_DELIVERY` event
`updated_at`	Timestamp when the delivery info was updated.	All events
`description`	A user-friendly display string in english explaining the webhook event, meant to show to customers on a tracking page.	All events

Return and undeliverable reasons

Use this table to learn more about the return reason and undeliverable reason you received in your webhooks.

Reason	Reason Comments
missing_unit_gate_code	Runner is unable to access apartment because of missing gate code or drop off instructions
cant_find_apartment_unit	Runner unable to find the specific apartment number or safe drop off location
business_closed	Commercial business closed and runner is unable to leave package in safe location.
incorrect_address	Incorrect address location or the address could be inaccessible such as a military base
technology_issue	Unable to complete delivery because of an runner app bug
route_abandoned	Route too long or late runner returned back to sortation center
recipient_refused	Package refused by recipient
emergency	Weather, safety, or runner related emergency
other	Runner put in a custom reason, does not know the reason, or language barrier

Delayed and awaiting reasons

Use this table to learn more about the delayed reason and awaiting reason you received in your webhooks.

Reason	Reason Comments	Reason Type
missing_from_truck	Package is missing from a truck, where awaiting indicates it's missing from a merchant truck	Delayed/Awaiting
driver_unassigned	Package is unassigned from a driver	Delayed
misplaced_at_sortation	Package misplaced at a sortation site	Delayed
other	Other reason that is not currently supported or mapped	Delayed/Awaiting

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 payloads

{
  "created_at": "2024-08-07T15:10:53.257097Z",
  "event_name": "PARCEL_LABELED",
  "external_delivery_id": "DDNAP5V14ZOD5L6JA",
  "dasher_name": "",
  "pickup_address": "16270 Raymer Street, Los Angeles, CA 91406",
  "pickup_phone_number": "+18559731040",
  "pickup_instructions": "",
  "pickup_reference_tag": "DDNAP5V14ZOD5L6JA",
  "pickup_external_business_id": "DoorDash",
  "pickup_external_store_id": "LAV-1",
  "dropoff_address": "1201 3rd Avenue, Seattle, WA 98101",
  "dropoff_phone_number": "+18559731040",
  "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": 15120,
  "currency": "USD",
  "pickup_time_estimated": "2024-08-10T03:08:25.000000Z",
  "dropoff_time_estimated": "2024-08-10T03:49:00.000000Z",
  "fee": 1200,
  "tip": 0,
  "support_reference": "1343594362",
  "tracking_url": "https://track.doordash.com/order/DDNAP5V14ZOD5L6JA/track?origin=drive_webhook_v2",
  "contactless": true,
  "updated_at": "2024-08-07T15:10:37.826741Z",
  "description":"Your package has a shipping label and being prepared to ship."
}


{
  "created_at": "2024-08-07T14:39:18.153802Z",
  "event_name": "PARCEL_SCANNED",
  "external_delivery_id": "DDNAP5V14ZOD5L6JA",
  "dasher_name": "",
  "pickup_address": "16270 Raymer Street, Los Angeles, CA 91406",
  "pickup_phone_number": "+18559731040",
  "pickup_instructions": "",
  "pickup_reference_tag": "DDNAP5V14ZOD5L6JA",
  "pickup_external_business_id": "DoorDash",
  "pickup_external_store_id": "LAV-1",
  "dropoff_address": "1201 3rd Avenue, Seattle, WA 98101",
  "dropoff_phone_number": "+18559731040",
  "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": 15120,
  "currency": "USD",
  "pickup_time_estimated": "2024-08-08T03:10:24.000000Z",
  "dropoff_time_estimated": "2024-08-08T03:49:00.000000Z",
  "fee": 1200,
  "tip": 0,
  "support_reference": "1343594362",
  "tracking_url": "https://track.doordash.com/order/DDNAP5V14ZOD5L6JA/track?origin=drive_webhook_v2",
  "contactless": true,
  "updated_at": "2024-08-07T14:39:17.936039Z",
  "package_location":{
    "city":"Los Angeles",
    "state":"CA",
    "zip_code":"91406",
    "timezone":"US/Pacific"
    },
  "description":"Your package was received at a local facility and will go out for delivery shortly."
}


{
  "created_at": "2024-08-07T08:35:41.935429Z",
  "event_name": "DASHER_DROPPED_OFF",
  "external_delivery_id": "DDNAP5V14ZOD5L6JA",
  "dasher_id": 14293861,
  "dasher_name": "TAS-DASHER-54 T.",
  "dasher_phone_number": "+19452623875",
  "dasher_dropoff_phone_number": "+19452623875",
  "dasher_pickup_phone_number": "+16284660361",
  "dasher_location": {
    "lat": 30.4674176,
    "lng": -97.6781026
  },
  "dasher_vehicle_make": "",
  "dasher_vehicle_model": "",
  "dasher_vehicle_year": "",
  "pickup_address": "16270 Raymer Street, Los Angeles, CA 91406",
  "pickup_phone_number": "+18559731040",
  "pickup_instructions": "",
  "pickup_reference_tag": "DDNAP5V14ZOD5L6JA",
  "pickup_external_business_id": "DoorDash",
  "pickup_external_store_id": "LAV-1",
  "dropoff_address": "1201 3rd Avenue, Seattle, WA 98101",
  "dropoff_phone_number": "+18559731040",
  "dropoff_instructions": "please take it to floor 21",
  "dropoff_contact_given_name": "John",
  "dropoff_contact_family_name": "Doe",
  "dropoff_contact_send_notifications": false,
  "order_value": 15120,
  "currency": "USD",
  "pickup_time_estimated": "2024-08-07T08:35:39.000000Z",
  "pickup_time_actual": "2024-08-07T08:35:39.039191Z",
  "dropoff_time_estimated": "2024-08-08T18:50:00.000000Z",
  "dropoff_time_actual": "2024-08-07T08:35:41.634432Z",
  "fee": 1200,
  "tip": 0,
  "support_reference": "DDNAP5V14ZOD5L6JA",
  "tracking_url": "https://track.doordash.com/order/2743268f-ae39-4863-93ee-fafa5ad02b90/track?origin=drive_webhook_v2",
  "contactless": true,
  "updated_at": "2024-08-07T08:32:49.035916Z",
  "dropoff_verification_image_url": "https://developer.doordash.com/en-US/img/simulator/frontdoor.png",
  "package_location": {
    "city": "",
    "state": "",
    "zip_code": "",
    "timezone": "US/Pacific"
  },
  "description":"Your package has been delivered."
}

Webhooks for parcel orders

Events​

All parcels​

Parcels with mid-mile hops​

Parcels with failed delivery attempts​

Parcels with exception statuses​

Fields​

Return and undeliverable reasons​

Delayed and awaiting reasons​

Data formats​

Retries​

Example webhook payloads​