Webhooks & Event Streams

Receive asynchronous notifications on shipment state transitions and storefront order events.

Tumr pushes outbound webhook notifications to URLs you configure — there is no separate webhook-registration endpoint.

Configuring a Destination

Per shipment: pass a webhook_url parameter when creating a shipment via POST /api/v1/shipments/.
Per store: set the store's webhook URL in your dashboard settings to receive storefront order events.

Destination URLs must be public HTTPS endpoints; internal or unsafe addresses are rejected.

Event Names

Shipment lifecycle events include shipment.created, shipment.claimed, shipment.assigned, shipment.arrived, shipment.exception, and delivery.completed. Storefront order events use the order.<status> naming pattern (for example order.placed, order.delivered).

Payload & Signature

Each delivery is a JSON body signed with HMAC-SHA256. The signature is sent as a raw hex digest in the X-Tumr-Signature header; storefront events additionally include an X-Tumr-Event header naming the event. See the [HMAC Webhook Verification](/en/docs/guides/webhook-integration/) guide for verification code.

{
  "event": "shipment.assigned",
  "shipment_id": "76495b28-1004-4b52-9fe1-d64e8e5ab190",
  "tracking_number": "AKR-83491054",
  "timestamp": 1755199200.0,
  "status": "IN_TRANSIT",
  "merchant_reference": "INV-1042",
  "service_level": "EXPRESS",
  "rider_email": "[email protected]",
  "carrier_name": "[email protected]",
  "updated_at": "2025-08-14T13:20:00.000000+00:00"
}

Failed deliveries are retried automatically by the task queue. You can also trigger a resend for a specific shipment via POST /api/v1/webhooks/resend/.