RouteOneHelp Center

Webhooks

Receive signed order and tracking events at your own endpoint, and verify each request with HMAC-SHA256.

Webhooks let RouteOne call your server whenever an order or shipment changes, so you do not have to keep polling the tracking endpoint. Each payload is signed with a secret you choose, so you can check that it really came from RouteOne.

Set up a webhook

  1. 1Open Settings and choose Webhooks.
  2. 2Click Setup New Webhook.
  3. 3Choose the Event: Tracking Update or Order Update. Add a Description if you like.
  4. 4Enter your Endpoint URL. It must be a public http or https address; local and private addresses are refused.
  5. 5Set a Signing Secret of at least 8 characters. Store it on your server.
  6. 6Click Save Webhook, or Save & Test to save it and send a sample request straight away.

From the list you can Test a webhook again, Pause and Enable it, or delete it.

Events and payloads

RouteOne sends a POST with a JSON body. Any 2xx response marks it delivered. Otherwise it is retried, up to 5 attempts. Requests time out after 10 seconds, so reply quickly and do heavy work afterwards.

Event typeWhen it firesBody fields
ORDER_UPDATEAn order is created (from the API, dashboard, import or a channel) or cancelled. Events: created, cancelled.type, event, timestamp, order_id (your reference), order_ref_id (RouteOne id), status, and shipment_id on created.
TRACKING_UPDATEA shipment's status changes. Event is one of SHIPPED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, RTO, NDR, CANCELLED, or the raw status for other changes.type, event, timestamp, shipment_id, awb, status, courier, order_id.

The Test button sends a sample body with sample: true and event: "test", so you can wire up your receiver before real events arrive.

Headers

  • X-RouteOne-Event is the event name.
  • X-RouteOne-Delivery is unique per delivery. Use it to ignore duplicates when a retry arrives.
  • X-RouteOne-Signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, using your signing secret.

Verify the signature

  1. 1Read the raw request body before parsing the JSON.
  2. 2Compute the HMAC-SHA256 of that body with your signing secret and prefix it with sha256=.
  3. 3Compare it with X-RouteOne-Signature using a constant-time comparison. Reject the request if it does not match.
  4. 4Check the body's timestamp and reject events older than a few minutes, to block replays.

In Node.js: const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex"), then compare with crypto.timingSafeEqual.

Do not re-serialise the JSON before checking the signature. Even a changed key order or spacing will produce a different hash. Always use the raw body as received.
Webhooks are one way to follow shipments. You can also read status on demand with GET /track. See API endpoints.

Still need help? Email support@routeone.app with your order ID or AWB, or raise a ticket from Help Center › Ticket in the app.