Introduction

Burq webhooks allow you to receive real-time updates when events occur across your deliveries, routes, and orders, without polling the API.

You can configure multiple webhook URLs, each subscribed to a specific set of event types. For example, one URL can receive delivery status updates while another receives route dispatch events.

Setup

Go to the Developer section of the Burq Dashboard to manage your webhooks.

Click Add Webhook, enter your endpoint URL, and select the event types you want to receive. A single URL can subscribe to any combination of events, and the same event can be sent to multiple URLs.

Webhook URLs are configured separately for production and test environments — use the environment toggle at the top of the screen to make sure you're configuring the right one.

Event Types

Delivery Events

Event	Description
`delivery.updated`	Fired when a delivery status changes, or when `pickup_eta` or `dropoff_eta` updates.
`delivery.courier_location_updated`	Fired when Burq receives a driver location update from a provider.
`delivery.rerouted`	Fired when a delivery is rerouted to a different provider.
`delivery_incident.created`	Fired when a delivery incident (e.g. cancellation, dispute) is created.
`delivery_incident.updated`	Fired when a delivery incident is updated.

Route Events

Event	Description
`route.quote_creation_started`	Fired when quote generation begins for a route.
`route.quote_creation_complete`	Fired when quotes are ready for a route.
`route.quote_creation_failed`	Fired when quote generation fails.
`route.quote_created`	Fired when an individual route quote is created.
`route.dispatched`	Fired when a route is dispatched to a provider.
`route.updated`	Fired when a route status changes.

Batch Events

Event	Description
`batch.order_creation_started`	Fired when batch order creation begins.
`batch.order_creation_complete`	Fired when batch orders are successfully created.
`batch.order_creation_failed`	Fired when batch order creation fails.
`batch.route_creation_started`	Fired when batch route creation begins.
`batch.route_creation_complete`	Fired when batch routes are successfully created.
`batch.route_creation_failed`	Fired when batch route creation fails.
`batch.quote_creation_started`	Fired when batch quote generation begins.
`batch.quote_creation_complete`	Fired when batch quotes are ready.
`batch.quote_creation_failed`	Fired when batch quote generation fails.
`batch.vehicle_recommendation_started`	Fired when vehicle recommendation begins for a batch.
`batch.vehicle_recommendation_complete`	Fired when vehicle recommendation completes.
`batch.vehicle_recommendation_failed`	Fired when vehicle recommendation fails.

Webhook Request Payload

All webhook events share the same top-level envelope:

{
  "object": "event",
  "type": "delivery.updated",
  "data": {
    // Event-specific payload
  }
}

For delivery events, the data object is a Delivery resource. You can find full property documentation in Creating Delivery Requests.

The status_history field on the Delivery resource records each status transition with its timestamp:

"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", "created": "2022-11-26T19:40:00.000Z" },
  { "status": "delivered", "created": "2022-11-26T19:41:00.000Z" }
]

delivery.rerouted

When a delivery is rerouted, Burq cancels the original and creates a new delivery with a new ID — future updates will only be sent under the new delivery ID. The payload includes both:

{
  "object": "event",
  "type": "delivery.rerouted",
  "data": {
    "parent_delivery": {
      // Original Delivery resource
    },
    "child_delivery": {
      // New Delivery resource
    }
  }
}

delivery_incident.created / delivery_incident.updated

The data object is a Delivery Incident resource — see GET Delivery Incident for the full schema.

Webhook Security

Each webhook request includes a Burq-Signature header you can use to verify the request came from Burq:

Burq-Signature: t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Burq signs requests using HMAC with SHA-256. Your signing secret is available in the Dashboard under Developer → Signing Secret. Each environment (production / test) has its own secret.

Step 1: Extract timestamp and signature

Split the header on ,, then split each part on = to get key-value pairs:

t → timestamp
v1 → signature

Step 2: Construct the signed payload

Concatenate:

The timestamp value
A literal .
The raw JSON request body

Step 3: Compute and compare

Compute HMAC-SHA256(payload, signingSecret) and compare it to the v1 value using a constant-time string comparison to prevent timing attacks.

As an additional check, compare the timestamp against the current time and reject requests that are too old.