Webhooks

Webhooks push order updates to you in real time, so you don’t have to poll. When an order changes status, Sparqle sends an HTTP POST to the URL you’ve registered for that event.

Setup

Webhook URLs are configured per company and per event (status). Provide your endpoint(s) to your Sparqle contact, specifying which statuses you want to receive. You can register different URLs for different statuses, or one URL for all of them.

Webhooks are environment-specific. Register your production endpoint against the live environment separately from any test endpoint.

The request

Sparqle sends a POST with a fixed JSON payload. The shape is stable — fields won’t be removed or renamed as the platform evolves.

POST https://your-app.com/webhooks/sparqle
Content-Type: application/json; charset=UTF-8

{
  "id": 1,
  "orderId": "SPQ-10293",
  "orderRef": "PADE3JWEA",
  "status": "out_for_delivery",
  "previousStatus": "in_transit",
  "attempt": 1,
  "barcode": "3STBXX123456789",
  "name": "iPod",
  "weight": 1500,
  "length": 200,
  "width": 75,
  "height": 50,
  "isBusiness": false,
  "mailbox": false,
  "locationId": 7,
  "orderBundle": {
    "id": 7419,
    "bundleId": "4OXMV95NH7YSGP3ZERJD2"
  },
  "deliveryName": "Jane Doe",
  "deliveryEmail": "[email protected]",
  "deliveryPhone": "+31612345678",
  "deliveryAddress": "Gustav Mahlerlaan 320, 1082 ME Amsterdam, NL",
  "deliveryAddressObject": {
    "street": "Gustav Mahlerlaan",
    "houseNumber": "320",
    "suffix": "",
    "postalCode": "1082 ME",
    "city": "Amsterdam",
    "countryCode": "NL"
  },
  "deliveryNote": "Leave at the door",
  "deliveryDate": "2026-06-27T00:00:00.000Z",
  "deliveryEta": "2026-06-26T12:40:00.000Z",
  "trackingUrl": "https://tracking.sparqle.com/barcode/3STBXX123456789",
  "createdAt": "2026-06-25T09:00:00.000Z",
  "updatedAt": "2026-06-26T10:15:00.000Z",
  "sortedAt": "2026-06-26T08:30:00.000Z",
  "completedAt": "2026-06-26T13:05:00.000Z",
  "signee": "J. Doe",
  "signatureImage": "data:image/png;base64,iVBORw0KG...",
  "riderNote": "Rang doorbell twice",
  "pods": ["https://cdn.sparqle.com/pod/abc.jpg"],
  "neighbourAddress": "Gustav Mahlerlaan 322, 1082 ME Amsterdam"
}

Field	Type	Description
`id`	number	Sparqle’s internal order id.
`orderId`	string	Sparqle’s order identifier.
`orderRef`	string	Your reference, as supplied on create.
`status`	string	The status the order just entered.
`previousStatus`	string \| null	The status it moved from.
`attempt`	number	Delivery attempt count.
`barcode`	string \| null	Parcel barcode.
`name`	string \| null	Order name.
`weight`	number \| null	Parcel weight in grams.
`length`	number \| null	Parcel length in mm.
`width`	number \| null	Parcel width in mm.
`height`	number \| null	Parcel height in mm.
`isBusiness`	boolean \| null	Whether the delivery is to a business address.
`mailbox`	boolean	Whether it’s a mailbox delivery.
`locationId`	number \| null	Pickup location the order belongs to.
`orderBundle`	object \| null	Bundle the order is grouped in (`id`, `bundleId`), if any.
`deliveryName`	string \| null	Recipient name.
`deliveryEmail`	string \| null	Recipient email.
`deliveryPhone`	string \| null	Recipient phone.
`deliveryAddress`	string \| null	Formatted delivery address.
`deliveryAddressObject`	object \| null	Structured delivery address (`street`, `houseNumber`, `suffix`, `postalCode`, `city`, `countryCode`).
`deliveryNote`	string \| null	Delivery instructions from the recipient.
`deliveryDate`	string \| null	Requested delivery date (ISO 8601).
`deliveryEta`	string \| null	Estimated delivery time (ISO 8601).
`trackingUrl`	string \| null	Public tracking page.
`createdAt`	string	When the order was created (ISO 8601).
`updatedAt`	string	When the order was updated (ISO 8601).
`sortedAt`	string \| null	When the parcel was scanned at central sorting (ISO 8601).
`completedAt`	string \| null	When the order was delivered (ISO 8601).
`signee`	string \| null	Name of the person who signed for delivery.
`signatureImage`	string \| null	Base64-encoded signature image, when captured.
`riderNote`	string \| null	Note left by the rider.
`pods`	string[]	Proof-of-delivery photo URLs. Empty when none.
`neighbourAddress`	string \| null	Address it was delivered to, if left with a neighbour.

Match incoming webhooks to your own records on orderRef (your reference) or orderId (Sparqle’s). The status field tells you which lifecycle stage the order just entered; previousStatus lets you ignore out-of-order or duplicate deliveries.

Responding

Return a 2xx status code as quickly as possible to acknowledge receipt. Do any heavy processing asynchronously after you’ve responded — a slow endpoint can cause retries or timeouts.

Best practices

Be idempotent. The same status may be delivered more than once; dedupe on orderId + status.
Don’t assume ordering. Network timing means events can arrive out of order. Trust the status value, and ignore transitions that move backwards.
Verify the source. Restrict your endpoint to Sparqle (for example with a shared secret path or an allowlist) and only accept expected statuses.

Get started

Core concepts

Guides

Setup

The request

Responding

Best practices

​Setup

​The request

​Responding

​Best practices

Setup

The request

Responding

Best practices