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

Route Events

Batch Events

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.

Handling Events

Terminal — the operation is over, no further event is coming

Non-terminal — cancelled, but Burq is still working the order

A cancelled delivery status does not mean the order has failed. Any cancel status — provider_canceled, burq_canceled, or customer_canceled — can be the first step of a reroute. Always check reroute.reroute_status before treating a cancellation as final.

Progress events - events which are sent for progress tracking

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:

1. The timestamp value
2. A literal .
3. 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.