DSP API Webhooks (1.0.0)

DSP API client should be able to receive updates about a delivery by subscribing to webhooks.
The DSP API provider should send delivery updates to the client as a REST payload.
The client's app will provide an internet-accessible REST endpoint that will receive and process the webhooks as payload in text/plain format.
Webhooks enable near-real-time information flow from DSP API and Drivers to client application and client customers.
With webhooks, your clients can enable real-time scenarios like a map view showing their customers how far away their Drivers are, push notifications telling client customers the latest status of their order, and much more.

The endpoint that will receive DSP API webhooks must be an HTTPS endpoint and should be protected with authentication.
DSP API should send webhooks protected by Basic Authentication.
The client will provide the contents that DSP API should send in the HTTP Authorization header when sending webhooks.

All Deliveries

DSP API should send webhooks for the following events, as soon as the event takes place:

• DRIVER_CONFIRMED: A Driver has accepted your delivery and is on the way to the pickup location.
• DRIVER_CONFIRMED_PICKUP_ARRIVAL: The Driver has confirmed that they arrived at the pickup location and are attempting to pick up the delivery.
• DRIVER_PICKED_UP: The Driver has picked up the delivery.
• DRIVER_CONFIRMED_DROPOFF_ARRIVAL: The Driver has confirmed that they arrived at the dropoff location.
• DRIVER_DROPPED_OFF: The Driver has dropped off the delivery at the dropoff location, and the delivery is complete.
• DELIVERY_CANCELLED: The delivery has been canceled.

Return-to-Pickup Deliveries Only

Deliveries that can be returned-to-pickup may generate webhooks for the following events:

• DELIVERY_RETURN_INITIALIZED: The Driver 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.
• DRIVER_CONFIRMED_RETURN_ARRIVAL: The Driver 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 (with reason = failed_to_return): The delivery was unable to be returned.

Delivery Tracking

DSP API can also provide various driver_enroute webhooks that send the location of the Driver every N seconds/minutes.

• DRIVER_ENROUTE_TO_PICKUP: The Driver is on their way to pick up the delivery.
• DRIVER_ENROUTE_TO_DROPOFF: The Driver is on their way to the dropoff location.
• DRIVER_ENROUTE_TO_RETURN: The Driver is on their way back to the pickup location to return the items.

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 Driver. Client code should always check if a field is present before accessing it.

Field	Description	Applicable Events
cancellation_reason	Why the order was canceled	Only the DELIVERY_CANCELLED event
cancellation_reason_message	Why the order was canceled, in the Driver'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	All events
driver_id	The unique identifier for the Driver	All events
driver_name	The first name and last initial of the Driver	All events
driver_dropoff_phone_number	The phone number of the Driver for the dropoff contact to use	All events
driver_pickup_phone_number	The phone number of the Driver for the pickup contact to use	All events
driver_location	Latitude and longitude of the Driver	All events
driver_vehicle_make	Make of the Driver's vehicle	All events
driver_vehicle_model	Model of the Driver's vehicle	All events
driver_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 DSP API 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 DRIVER_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 DRIVER_DROPPED_OFF
dropoff_signature_image_url	The signature image obtained from the customer when the order was dropped off if applicable	All events after and including DRIVER_DROPPED_OFF

Cancellation reasons client may receive in webhook.

Reason	Reason Comments
cancel_by_dispatch	Order was cancelled by DSP 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
driver_cannot_fulfill_other	The Driver couldn't fulfill the order
driver_not_responding	The Driver 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	DSP suspects this order is fraudulent
items_temporarily_unavailable	Items were temporarily unavailable
no_available_drivers	No Drivers are available for this order
nontablet_protocol_issue	DSP didn't receive the full order
other	DSP encountered an unknown error
picked_up_by_other_driver	Order was picked up by another Driver
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 Driver 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
package_lost_at_facility	The package was lost after receiving

All ...time... fields are sent as ISO-8601 date and times and are therefore sent in the UTC time zone.

• 401 Unauthorized: If the external_delivery_id is invalid or the Authorization header is incorrect.
• 400 Bad Request: If the request contains invalid data or is missing required fields.

DSP API should authenticate with the following header format:

Authorization: <Auth Content from Client>

Webhook Payload (POST request):

{
  "created_at": "2022-02-01T23:18:22.791883Z",
  "event_name": "DRIVER_DROPPED_OFF",
  "external_delivery_id": "c19a5d37-e457-4247-9a67-921ec0134125",
  "driver_id": 123212,
  "driver_name": "John D.",
  "driver_dropoff_phone_number": "+16504379788",
  "driver_pickup_phone_number": "+16504379799",
  "driver_location": {"lat": 43.333333333, "lng": -79.333333333},
  "driver_vehicle_make": "Honda",
  "driver_vehicle_model": "Civic",
  "driver_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_external_store_id": "ase-243-dzs",
  "external_business_id": "local_default",
  "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://dspapi.com/drive/portal/track/53904a0b-18cd-4308-b6dc-1d83932d7990",
  "contactless": false
}