Introduction
Burq's webhooks allow you to receive updates when status changes occur to an order. This way you do not need to poll our API for updates, but can instead receive and react to them as they happen. There are different events you can subscribe to. Collectively, these webhook events enable a number of use cases such as providing delivery status update, driver information and location update, eta update and etc.; notifying delivery reroute events; and allowing merchant application to programmatically track refund statuses.
To start receiving webhooks, first provide a url from the Developer section of Burq Dashboard (as shown below). Webhook url is configured separately for production and test environments. Please use the test mode toggle at the top of the screen to make sure you configure the url for the right environment.
Once a webhook url is configured, you can now choose the webhook events you want to subscribe to.
Webhook Request Payload
All webhooks are sent with the following top-level request payload:
{
object: "event",
type: "delivery_incident.updated" // or other event names
data: {
// Each event may use different API resource. See below for documentation on the respective
// event payload.
}
}
delivery.updated event
delivery.updated events are sent whenever Burq receives information from providers about deliveries under your account. The data object included in these events is the Delivery API resource. You can find detailed documentation for the included properties in Creating Delivery Requests.
Events that trigger webhook deliveries include:
- Delivery status updates from provider.
- Delivery status changes when you call Burq V1 cancel-delivery API or cancel a delivery via Burq dashboard.
- Delivery ETA updates (whenever the
pickup_etaanddropoff_etaproperties change). - Driver location updates.
Below is a sample payload sent to the webhook address as a POST request when the status is first updated.
{
"id": "19g68lawsqlrf",
"delivery_type": "asap",
"service": "doordash",
"status": "delivery_created",
"tracking_url": "https://burqup.com/track/19g68lawsqlrf",
// Cost of delivery properties
"currency": "USD",
"fee": 869,
"payment_amount": 869,
"tip": 300,
"upsell": null,
"subsidized": null,
// General delivery properties
"created_at": "2022-11-25T17:47:37.000Z",
"cancellation_reason": null,
"external_order_ref": "FantasyStore-Order#42123",
"order_value": 4489,
"proof_of_delivery": [],
"quote_id": "19g68lawsqlqj",
"signature": null,
"status_history": [],
"store_id": null,
"test_mode": true,
"updated_at": "2022-11-25T17:47:37.000Z",
"vehicle": null,
// Pickup and dropoff properties
"pickup_at": null,
"pickup_address": "43 E Ohio St, Chicago, IL 60611, USA",
"pickup_eta": "2022-11-25T18:00:00.000Z",
"pickup_name": "Eataly Restaurant",
"pickup_notes": "Please look for package with order label #42123.",
"pickup_phone_number": "15124439077",
"pickup_unit": "Unit 3211",
"dropoffs": [
{
"dropoff_at": null,
"dropoff_address": "233 S Wacker Dr, Chicago, IL 60606, USA",
"dropoff_eta": "2022-11-25T18:30:00.000Z",
"dropoff_name": "John Doe",
"dropoff_notes": "Please call upon arrival",
"dropoff_phone_number": "14342118980",
"dropoff_unit": "Apartment 908",
}
],
// Delivery items
"items_description": "Food items",
"items": [
{
"name": "Brisket Classic",
"quantity": 4,
"size": "small"
}
],
// Driver properties
"courier_name": null,
"courier_img": null,
"courier_phone_number": null,
"courier_vehicle_type": null,
"courier_location_lat": null,
"courier_location_lng": null
}
Note that the status_history field contains a list of statuses with the date that status was set. As a Delivery transitions through different statuses, those transitions will be recorded in the status_history field. Please see below for a sample data structure of this property:
{
// ...
"status_history": [
{
"status": "delivery_created",
"created": "2022-05-31T14:58:56+00:00"
},
{
"status": "driver_assigned",
"created": "2022-05-31T15:00:30+00:00"
}
]
}
The status_history field of a successfully completed Delivery may look like this:
"status_history": [
{
"status": "delivery_created",
"created": "2022-11-26T19:05:24.000Z"
},
{
"status": "driver_assigned",
"created": "2022-11-26T19:05:34.000Z"
},
{
"status": "enroute_pickup",
"created": "2022-11-26T19:05:38.000Z"
},
{
"status": "arrived_at_pickup",
"created": "2022-11-26T19:15:49.000Z"
},
{
"status": "pickup_complete",
"created": "2022-11-26T19:16:00.000Z"
},
{
"status": "enroute_dropoff",
"created": "2022-11-26T19:21:00.000Z"
},
{
"status": "arrived_at_dropoff",
"status": "2022-11-26T19:40:00.000Z"
},
{
"status": "delivered",
"created": "2022-11-26T19:41:00.000Z"
}
]
delivery.rerouted event
When a delivery provider is having trouble finding drivers for a delivery or otherwise fulfilling the delivery, Burq may "reroute" the delivery to another provider (to learn more about enabling this option for your account, please reach out to your account manager or Burq support). When a delivery is rerouted, Burq system cancels the old delivery and creates a new delivery. This new delivery has a different Burq-generated id, and delivery updates henceforth will only be provided under the new delivery (and not reflected on the old delivery).
Merchants who want to track delivery reroutes can subscribe to the delivery.rerouted event. This event is fired whenever a delivery is rerouted, and has the following request payload:
{
"object": "event",
"type": "delivery.rerouted",
"data": {
"parent_delivery": {
// Delivery API Resource
},
"child_delivery": {
// Delivery API Resource
}
}
}
delivery_incident.created/updated events
Burq system creates delivery incidents automatically in response to potential refund events, such as when a delivery is canceled by provider or when a delivery is disputed by merchants. Merchants who want to programmatically monitor the refund status of delivery incidents can subscribe to delivery_incident.created and delivery_incident.updated events. Both events send Delivery Incident API resource under the data property. For more information on the Delivery Incident API resource, please refer to the response payload of GET Delivery Incident API.
Upgrading to Latest Webhooks Version
For merchants on older webhook versions (most merchants who signed up prior to July 2023), please refer to this guide on how to upgrade to the latest webhook version.