DSP API Webhooks (1.0.2)

DSP API client should be able to receive updates about deliveries by subscribing to webhooks.
The DSP API provider should send delivery updates to the client as a REST payload.
The client's app provides an internet-accessible REST endpoint that receives and processes the webhooks as a payload in text/plain format.
Webhooks enable near-real-time information flow from DSP API and Drivers to client application and 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 customers the latest status of their order, and much more.

Note: Credentials for calling the DSP API (Developer ID, Client ID / Key ID, Client Secret) and their formats (UUID, Secret generation) are described in the main DSP API documentation (Authorization section). This document describes only how the provider sends webhooks to the client (Webhook URL, Webhook Auth Header).

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 content that the DSP API should include in the HTTP Authorization header when sending webhooks.

Webhook Authorization Header

When this system acts as DSP API provider, it sends webhooks to the URL configured in the DSP Clients section (Webhook Url field).
For each DSP API client you can configure the exact value of the HTTP Authorization header that the provider will send with every webhook in DSP Clients → Webhook Auth Header.
This value is stored as‑is and forwarded unchanged in the Authorization header of outbound webhook requests.

Format of the header value (Basic Auth):

• To use Basic Auth, build the credential string by Base64‑encoding username:password (this is Base64‑encoding, not encryption).
  
• The final HTTP header value should look like: Authorization: Basic <base64(username:password)>.
  
• In the UI you must enter only the header value part into Webhook Auth Header, for example: Basic d2ViaG9va191c2VyOnN0cm9uZ19wYXNzd29yZA==.
  

Length and recommendations:

• The stored header value must not exceed 255 characters.
  
• The secret (the password part of username:password) should be at least 16 characters before Base64 encoding; and longer random secrets are preferred for security.
  
• You can generate a strong random secret in your application code, for example:

import java.security.SecureRandom;
import java.util.Base64;

byte[] randomBytes = new byte[32];
new SecureRandom().nextBytes(randomBytes);

String secret = Base64.getUrlEncoder().withoutPadding().encodeToString(randomBytes);
System.out.println(secret);

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 (this is the preferred behavior for optional fields).
Sending a field explicitly as null is technically allowed, but omitting absent/empty optional fields results in a cleaner payload.
For example, pickup_time_actual is not included in webhook payloads until the delivery has been picked up by the Driver.
Client implementations must ignore unknown fields in the webhook payload to remain forward‑compatible with future extensions of this API.
Client code should always check if a field is present before accessing it.

Dropoff address vs. dropoff location:

• dropoff_address is the primary field and should be used for serviceability checks, pricing, and most business logic.
  
• dropoff_location (an object with lat/lng) can be used, when present, for more accurate driver navigation only.
  
• If both dropoff_address and dropoff_location are present, the address has priority for fee and serviceability calculations, while the location is only a hint for navigation.
  
• In the current implementation, this system does not include a separate dropoff_location field in webhook payloads; only dropoff_address is sent.
  

Per-event required fields:

• All webhook events always include: event_name, external_delivery_id, and created_at. These fields are required to identify the delivery and the event.
  
• Driver-related events (for example, DRIVER_CONFIRMED, DRIVER_CONFIRMED_PICKUP_ARRIVAL, DRIVER_PICKED_UP, DRIVER_CONFIRMED_DROPOFF_ARRIVAL, DRIVER_DROPPED_OFF, DRIVER_ENROUTE_*) require a valid driver_id. If a driver-related event is received without driver_id, it is treated as invalid and will be rejected.
  
• When updating driver information via webhooks, driver_name and driver phone numbers are optional, but they are processed only when a valid driver_id is present. If driver_name is sent without driver_id, the driver information for the delivery is not updated.
  
• The DELIVERY_CANCELLED event may include cancellation_reason and cancellation_reason_message. cancellation_reason is optional but recommended; when present, it should be one of the values listed in the Cancellation Reasons section.
  

Field	Type	Description	Required	Applicable Events
cancellation_reason	enum string (see Cancellation Reasons)	Why the order was canceled	No	Only the DELIVERY_CANCELLED event
cancellation_reason_message	string	Why the order was canceled, in the Driver's words	No	Only the DELIVERY_CANCELLED event and only if cancellation_reason = failed_to_return
contactless	boolean	Whether the delivery was contactless or normal	No	All events
created_at	datetime (ISO‑8601, UTC)	When the webhook was created	Yes	All events
currency	currency code (ISO‑4217)	The currency of order_value, fee, and tip in cents	No	All events
driver_id	integer	The unique identifier for the Driver. Required for driver-related events (e.g. DRIVER_CONFIRMED, DRIVER_PICKED_UP, DRIVER_DROPPED_OFF, DRIVER_ENROUTE_*); if missing in such events, the webhook is rejected. Optional for DELIVERY_CANCELLED.	Yes (driver-related events)	All events
driver_name	string	The first name and last initial of the Driver	No	All events
driver_dropoff_phone_number	string (E.164 phone)	The phone number of the Driver for the dropoff contact to use	No	All events
driver_pickup_phone_number	string (E.164 phone)	The phone number of the Driver for the pickup contact to use	No	All events
driver_location	object {lat: number, lng: number}	Latitude and longitude of the Driver	No	All events
driver_vehicle_make	string	Make of the Driver's vehicle	No	All events
driver_vehicle_model	string	Model of the Driver's vehicle	No	All events
driver_vehicle_year	string or integer	Year of the Driver's vehicle	No	All events
dropoff_address	string	Where the delivery will be dropped off	No	All events
dropoff_contact_family_name	string	Family name of the contact	No	All events
dropoff_contact_given_name	string	Given name of the contact	No	All events
dropoff_contact_send_notifications	boolean	Whether the contact will receive notifications from DSP API for this delivery; default is false	No	All events
dropoff_instructions	string	Instructions for the Driver to follow when dropping off the order	No	All events
dropoff_phone_number	string (E.164 phone)	The phone number for the Driver to call if there are issues with the delivery	No	All events
dropoff_requires_signature	boolean	DEPRECATED. See main DSP API documentation. Use dropoff_options.signature instead (supports required, preferred, none).	No	All events
dropoff_time_actual	datetime (ISO‑8601, UTC)	When the delivery was dropped off	No	All events after and including DRIVER_DROPPED_OFF
dropoff_time_estimated	datetime (ISO‑8601, UTC)	When the delivery is estimated to be dropped off	No	All events
dropoff_verification_image_url	URL (absolute HTTPS)	The verification image taken by the Driver when the order was dropped off	No	All events after and including DRIVER_DROPPED_OFF
dropoff_signature_image_url	URL (absolute HTTPS)	The signature image obtained from the customer when the order was dropped off if applicable	No	All events after and including DRIVER_DROPPED_OFF
external_business_id	string	Unique ID of the business that initiates the request; used for billing purposes	No	All events
external_delivery_id	string	Unique ID of the delivery (generated by the client when creating the delivery)	Yes	All events
event_name	enum string	The webhook event type (e.g. DRIVER_DROPPED_OFF, DELIVERY_CANCELLED)	Yes	All events
order_contains	object (e.g. {alcohol: boolean})	Specifies restricted item(s) in the order (e.g. alcohol)	No	All events
pickup_address	string	Where the delivery will be picked up (comma-separated full address)	No	All events
pickup_instructions	string	Instructions for the Driver to follow when picking up the order	No	All events
pickup_phone_number	string (E.164 phone)	The phone number for the Driver to call if there are issues with the delivery	No	All events
pickup_external_store_id	string	Unique ID of the pickup location (store)	No	All events
pickup_time_estimated	datetime (ISO‑8601, UTC)	When the delivery is estimated to be picked up	No	All events
pickup_time_actual	datetime (ISO‑8601, UTC)	When the delivery was picked up by the Driver	No	All events after and including DRIVER_PICKED_UP
support_reference	string	Internal reference for this delivery; use when contacting DSP API support	No	All events
tracking_url	URL (absolute HTTPS)	Tracking page URL for the delivery (format may change over time)	No	All events
updated_at	datetime (ISO‑8601, UTC)	When the delivery state was last updated	No	All events

Cancellation reasons that may be sent in the DELIVERY_CANCELLED webhook event.
The values below are defined by the DSP API specification (see the main API documentation for the complete enum).
The ones marked with an asterisk (*) are the ones that this system (acting as DSP API provider) actually sends in webhooks when canceling deliveries.
Other DSP API providers may use different cancellation reason values, and all values from the specification enum are valid.

Reason	Reason Comments
cancelled_by_creator	The delivery was cancelled by the creator (the party that created the delivery request). This is the default reason when no specific reason is provided. Used in Cancel Delivery API responses.
cancelled_by_driver *	The delivery was cancelled by the Driver (the Driver initiated the cancellation).
cancelled_by_dispatcher *	The delivery was cancelled by a dispatcher or administrator in the system (not by the Driver).
failed_to_pickup	The delivery failed because the Driver could not pick up the order (e.g., restaurant not ready, service over-committed). Used in Cancel Delivery API responses.
failed_to_deliver	The delivery failed because the Driver could not complete the delivery (e.g., destination unreachable, package issues). Used in Cancel Delivery API responses.
failed_to_assign_and_refunded	The delivery failed because a Driver could not be assigned, and the payment was refunded (e.g., driver failure, incompatible delivery mode). Used in Cancel Delivery API responses.
failed_to_process_payment	The delivery was cancelled because payment processing failed.
failed_to_return	The delivery failed during the return process.

All ...time... fields are sent as ISO-8601 date and times and are therefore sent in the UTC time zone.
All monetary fields (such as order_value, fee, tip) are integers and represent the amount in the smallest currency unit (for example, cents for USD).
All phone number fields are strings in E.164 format (for example, +16504379788).
All URL fields are absolute HTTPS URLs.

• 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": "local_default_2heg7dxPdf_12345",
  "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",
  "order_contains": {"alcohol": false},
  "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",
  "dropoff_verification_image_url": "https://dspapi.com/deliveries/12345/dropoff-verification.jpg",
  "dropoff_signature_image_url": "https://dspapi.com/deliveries/12345/dropoff-signature.png",
  "fee": 975,
  "tip": 230,
  "support_reference": "1343593362",
  "tracking_url": "https://dspapi.com/drive/portal/track/53904a0b-18cd-4308-b6dc-1d83932d7990",
  "contactless": false
}

See Release Notes for the latest changes.