Webhooks

Webhooks are how DropHub tells your system that a shipment moved, without you polling for it. Managing them requires the webhooks:manage scope.

A merchant has one webhook. There is no collection of endpoints — the resource is /v2/external/webhook, singular, and creating a second one replaces nothing because there is nowhere to put it.

Register it

curl -X POST "$BASE_URL/v2/external/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example/webhooks/drophub"}'

Omit events to subscribe to all seven. To narrow it, name the ones you act on:

{
  "url": "https://merchant.example/webhooks/drophub",
  "events": ["shipment.delivered", "shipment.failed", "shipment.cancelled"]
}

The 201 response carries the endpoint and, exactly once, the signing secret:

{
  "webhook": {
    "endpointId": "0198f7c0-7f51-7000-8000-0000000000a1",
    "url": "https://merchant.example/webhooks/drophub",
    "status": "ACTIVE",
    "subscribedEventTypes": ["shipment.created", "shipment.assigned", "shipment.picked_up", "shipment.out_for_delivery", "shipment.delivered", "shipment.failed", "shipment.cancelled"],
    "previousSecretValidUntil": null,
    "version": 1,
    "createdAt": "2026-08-27T06:00:00Z",
    "updatedAt": "2026-08-27T06:00:00Z"
  },
  "signingSecret": "0mQ0Xy2h9pKQe3n5T1cVzR7bLd4WsJgYhA6uNfP8kEo"
}

signingSecret is disclosed on creation and on rotation, and never again. GET /v2/external/webhook returns the endpoint without it. Store it immediately; the recovery path is rotation, not retrieval.

Events

Event	Fires when
`shipment.created`	The shipment was accepted
`shipment.assigned`	A driver is on it
`shipment.picked_up`	Collected from the pickup point
`shipment.out_for_delivery`	On the way to the recipient
`shipment.delivered`	Delivered
`shipment.failed`	Delivery did not succeed
`shipment.cancelled`	Cancelled

These are the seven public statuses as they happen. DropHub’s internal dispatch steps do not appear here.

The delivery

{
  "id": "evt_0198f7c07f5170008000000000000301",
  "type": "shipment.delivered",
  "occurredAt": "2026-08-27T09:14:02Z",
  "sequence": 7,
  "apiVersion": "2026-08-27",
  "data": {
    "shipmentId": "0198f7c0-7f51-7000-8000-000000000001",
    "version": 7,
    "status": "DELIVERED"
  }
}

data.reasonCode is present on shipment.failed and shipment.cancelled. sequence is the shipment’s version and orders events for that shipment — ignore one you have already applied.

Verifying the signature

Every delivery carries three headers:

Header	Contents
`Webhook-Id`	Unique delivery identifier — deduplicate on this
`Webhook-Timestamp`	Unix timestamp in seconds
`Webhook-Signature`	`v1=` followed by a base64url, unpadded HMAC-SHA256

The signed message is those two values and the raw request body, joined with literal . characters:

{Webhook-Id}.{Webhook-Timestamp}.{raw body}

Two details break most first attempts:

The HMAC key is the decoded secret. signingSecret is 32 random bytes shown as base64url — base64url-decode it before using it as a key, do not pass the 43-character string.
The signature is base64url, not hex.

Verify against the raw bytes you received, before any JSON parsing or re-serialisation. Re-encoding the body changes it, and the signature will no longer match.

import base64, hashlib, hmac

def verify(signing_secret: str, webhook_id: str, timestamp: str,
           raw_body: bytes, header: str) -> bool:
    key = base64.urlsafe_b64decode(signing_secret + "=" * (-len(signing_secret) % 4))
    message = webhook_id.encode() + b"." + timestamp.encode() + b"." + raw_body
    digest = hmac.new(key, message, hashlib.sha256).digest()
    expected = "v1=" + base64.urlsafe_b64encode(digest).decode().rstrip("=")
    return hmac.compare_digest(expected, header)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(signingSecret, webhookId, timestamp, rawBody, header) {
  const key = Buffer.from(signingSecret, "base64url");
  const message = Buffer.concat([
    Buffer.from(`${webhookId}.${timestamp}.`), rawBody,
  ]);
  const expected = "v1=" + createHmac("sha256", key).update(message).digest("base64url");
  const a = Buffer.from(expected), b = Buffer.from(header);
  return a.length === b.length && timingSafeEqual(a, b);
}

Compare in constant time, as above. Also reject deliveries whose Webhook-Timestamp is far from your current clock — a valid signature on a very old request is a replay.

Responding

Return a 2xx quickly, then do the work. Acknowledge receipt and process asynchronously. Because retries exist, your handler must be idempotent: deduplicate on Webhook-Id, and ignore an event whose sequence you have already applied for that shipment.

Retries

A non-2xx, a timeout, or a transport failure is a failed attempt. DropHub retries up to 8 attempts, starting at 30 seconds and doubling each time, capped at 1 hour between attempts. A Retry-After on your 429 or 503 is honoured, up to that same 1-hour cap.

There is no delivery history, replay, or test-send API. If you need to re-drive state after an outage, read the shipments you care about with GET /v2/external/shipments/{id} — the current status is always authoritative.

Changing it

PATCH, DELETE, and rotation are conditional requests: they require the endpoint’s current version as an If-Match ETag. Read it from GET /v2/external/webhook, or from the ETag header of the response that last changed it. Pause while you deploy, rather than deleting and recreating — deletion loses the secret:

curl -X PATCH "$BASE_URL/v2/external/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "If-Match: \"1\"" \
  -H "Content-Type: application/json" \
  -d '{"status":"PAUSED"}'

PATCH accepts any of url, status (ACTIVE or PAUSED), and events.

curl -X DELETE "$BASE_URL/v2/external/webhook" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "If-Match: \"2\""

Omitting If-Match is rejected with 428; a stale one with 412. See Idempotency and ETags.

Rotating the secret

curl -X POST "$BASE_URL/v2/external/webhook/secret-rotations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "If-Match: \"2\""

Rotation returns a new signingSecret and sets previousSecretValidUntil on the endpoint — 24 hours ahead. Until that instant both secrets produce valid signatures.

Deploy the new secret alongside the old one and accept either during the overlap, then drop the old one once previousSecretValidUntil has passed. Rotating and cutting over in one step will drop deliveries that were already in flight.

Getting Started

Authentication

Shipments

Events

Request semantics

API reference

Register it

Events

The delivery

Verifying the signature

Responding

Retries

Changing it

Rotating the secret

​Register it

​Events

​The delivery

​Verifying the signature

​Responding

​Retries

​Changing it

​Rotating the secret

Register it

Events

The delivery

Verifying the signature

Responding

Retries

Changing it

Rotating the secret