Skip to main content

Webhook System Documentation

This document provides comprehensive documentation for our webhook system, detailing the event types, request body structure, and authentication mechanisms.

Event Types

Our webhook system dispatches requests based on specific event names, categorized primarily into delivery and location events. Each event signifies a distinct state change or action within our system.

Delivery Events

Delivery events provide updates on the lifecycle of a delivery, from assignment to completion or failure. The following is a comprehensive list of delivery event types:
  • delivery.assigned: A delivery has been assigned.
  • delivery.pickup_enroute: The delivery driver is enroute to the pickup location.
  • delivery.pickup_arrived: The delivery driver has arrived at the pickup location.
  • delivery.pickup_complete: The delivery driver has completed the pickup.
  • delivery.dropoff_enroute: The delivery driver is enroute to the dropoff location.
  • delivery.dropoff_arrived: The delivery driver has arrived at the dropoff location.
  • delivery.dropoff_complete: The delivery driver has completed the dropoff.
  • delivery.return_in_progress: The delivery is in the process of being returned.
  • delivery.returned: The delivery has been successfully returned.
  • delivery.canceled: The delivery has been canceled.
  • delivery.failed: The delivery has failed.

Location Events

Location events provide updates on the geographical status of a delivery or driver. The following is a comprehensive list of location event types:
  • location.pickup_enroute: The driver is enroute to the pickup location.
  • location.assigned_driver: A driver has been assigned to the delivery.
  • location.pickup_complete: The driver has completed the pickup and is now enroute to the dropoff.
  • location.dropoff_enroute: The driver is enroute to the dropoff location.
  • location.return_in_progress: The driver is in the process of returning to the origin.

Request Body Structure

All webhook requests are sent as POST requests with a JSON payload. The structure of the request body is consistent across all event types and contains detailed information pertinent to the event. Below is a breakdown of the fields included in the request body:
{
  "event_name": "string",
  "status": "string",
  "price": {
    "value": "number",
    "currency": "string"
  },
  "currency": "string",
  "distance": {
    "value": "number",
    "unit": "string"
  },
  "pickup_name": "string",
  "dropoff_name": "string",
  "delivery_date": "string",
  "delivery_start_time": "string",
  "partner_payload": "object",
  "driver_id": "number",
  "driver_name": "string",
  "driver_location": {
    "lat": "number",
    "lng": "number"
  },
  "driver_dropoff_phone_number": "string",
  "driver_pickup_phone_number": "string",
  "driver_vehicle_make": "string",
  "driver_vehicle_model": "string",
  "driver_vehicle_year": "number",
  "dropoff_time_estimated": "string",
  "pickup_address_street": "string",
  "pickup_address_city": "string",
  "pickup_address_country": "string",
  "pickup_address_number": "string",
  "pickup_address_county": "string",
  "pickup_address_state": "string",
  "pickup_address_postal_code": "string",
  "pickup_address_latitude": "number",
  "pickup_address_longitude": "number",
  "pickup_phone_number": "string",
  "pickup_instructions": "string",
  "email": "string",
  "dropoff_address_street": "string",
  "dropoff_address_city": "string",
  "dropoff_address_country": "string",
  "dropoff_address_number": "string",
  "dropoff_address_secondary_number": "string",
  "dropoff_address_county": "string",
  "dropoff_address_state": "string",
  "dropoff_address_postal_code": "string",
  "dropoff_address_latitude": "number",
  "dropoff_address_longitude": "number",
  "dropoff_phone_number": "string",
  "dropoff_instructions": "string",
  "dropoff_email": "string",
  "package_description": "string",
  "package_minimum_vehicle_size": "string",
  "package_delivery_mode": "string",
  "package_requirements": "array",
  "items_count": "number",
  "items": "array",
  "weight": "number",
  "dimentions": {
    "height": "number",
    "length": "number",
    "width": "number"
  },
  "package_value": "number",
  "pickup_start_time": "string",
  "dropoff_start_time": "string",
  "delivery_end_time": "string",
  "dropoff_verification_image_url": "string",
  "dropoff_signature_image_url": "string",
  "cancellation_reason": "string",
  "tip": "number",
  "partner_reference": "string"
}

Field Descriptions

Field NameTypeDescription
event_namestringThe specific webhook event that triggered the notification (e.g., pickup_complete).
statusstringThe current high-level status of the delivery task.
priceobjectAn object representing the total cost of the delivery.
price.valuenumberThe total price of the delivery in a standard decimal format, converted from cents.
price.currencystringThe ISO 4217 currency code for the price.
currencystringThe ISO 4217 currency code for the transaction.
distanceobjectAn object representing the estimated driving distance for the delivery.
distance.valuenumberThe estimated driving distance value (e.g., in kilometers).
distance.unitstringThe unit of measurement for the distance (e.g., kilometers).
pickup_namestringThe full name of the contact person at the pickup location.
dropoff_namestringThe full name of the contact person at the dropoff location.
delivery_datestringThe scheduled date for the delivery to begin, formatted as YYYY-MM-DD.
delivery_start_timestringThe scheduled start time for the delivery window, formatted as HH:MM:SS.
partner_payloadobjectAn arbitrary object provided by the partner during job creation for their own reference.
driver_idnumberA unique numeric identifier for the courier/driver.
driver_namestringThe full name of the assigned courier.
driver_locationobjectThe last known GPS coordinates of the driver.
driver_location.latnumberThe latitude of the driver’s location.
driver_location.lngnumberThe longitude of the driver’s location.
driver_dropoff_phone_numberstringThe driver’s phone number for dropoff-related communication.
driver_pickup_phone_numberstringThe driver’s phone number for pickup-related communication.
driver_vehicle_makestringThe make of the driver’s vehicle (e.g., Tesla).
driver_vehicle_modelstringThe model of the driver’s vehicle (e.g., Model Z).
driver_vehicle_yearnumberThe manufacturing year of the driver’s vehicle.
dropoff_time_estimatedstringThe estimated time of arrival at the dropoff location, in a standard datetime format.
pickup_address_streetstringStreet name of the pickup address.
pickup_address_citystringCity of the pickup address.
pickup_address_countrystringCountry of the pickup address.
pickup_address_numberstringStreet number of the pickup address.
pickup_address_secondary_numberstringApartment or suite number for the pickup address.
pickup_address_countystringCounty of the pickup address.
pickup_address_statestringState of the pickup address.
pickup_address_postal_codestringPostal or ZIP code of the pickup address.
pickup_address_latitudenumberLatitude coordinate of the pickup address.
pickup_address_longitudenumberLongitude coordinate of the pickup address.
dropoff_address_streetstringStreet name of the dropoff address.
dropoff_address_citystringCity of the dropoff address.
dropoff_address_countrystringCountry of the dropoff address.
dropoff_address_numberstringStreet number of the dropoff address.
dropoff_address_secondary_numberstringApartment or suite number for the dropoff address.
dropoff_address_countystringCounty of the dropoff address.
dropoff_address_statestringState of the dropoff address.
dropoff_address_postal_codestringPostal or ZIP code of the dropoff address.
dropoff_address_latitudenumberLatitude coordinate of the dropoff address.
dropoff_address_longitudenumberLongitude coordinate of the dropoff address.
pickup_phone_numberstringThe contact phone number for the pickup location.
pickup_instructionsstringSpecial instructions for the courier at the pickup location.
emailstringThe email address of the contact person at the pickup location.
dropoff_phone_numberstringThe contact phone number for the dropoff location.
dropoff_instructionsstringSpecial instructions for the courier at the dropoff location.
dropoff_email stringThe email of the entity to contact.
package_descriptionstringA description of the contents of the package being delivered.
package_minimum_vehicle_sizestringThe minimum vehicle size required for this delivery (e.g., CAR, BIKE).
package_delivery_modestringThe delivery mode, indicating if it’s on-demand (NOW) or scheduled.
package_requirementsarrayA list of special requirements for the delivery (e.g., photo_proof_of_delivery).
items_countnumberThe number of items in the package.
itemsarrayA list of objects, each detailing an item in the package. Can be null.
weightnumberThe weight of the package.
dimentionsobjectThe dimentions of the package.
package_valuenumberThe declared value of the package, converted from cents.
pickup_start_timestringThe start time of the pickup window, formatted as HH:MM:SS.
dropoff_start_timestringThe start time of the dropoff window, formatted as HH:MM:SS.
delivery_end_timestringThe end time of the dropoff window, formatted as HH:MM:SS.
dropoff_verification_image_urlstringURL to a photo taken as proof of delivery. Available on relevant events.
dropoff_signature_image_urlstringURL to a signature captured as proof of delivery. Available on relevant events.
cancellation_reasonstringThe reason for a delivery cancellation. Available on cancellation events.
tipnumberThe tip amount for the driver, converted from cents.
partner_referencestringA reference ID provided by the partner during job creation.

Authentication Headers

All webhook requests include the following headers:
HeaderDescription
Content-TypeSet to application/json
AcceptSet to application/json
AuthorizationBearer token containing a JWT encoded version of the request body.