Webhooks
Tujyane sends a POST to your webhook URL for each event of each Shipment. Use webhooks as the source of truth for what happened to a Shipment.
Set up your receiver
Section titled “Set up your receiver”Tujyane sets your webhook URL and gives you a webhook secret (whsec_...). Ask your Tujyane contact to set or change them.
- The URL must be
https. - Test and live events go to the same URL and are signed with the same secret. Use
modein each event to tell them apart. - Keep the secret on your server. Never put it in an app or a web page.
Check your receiver at any time with POST /webhooks/test. Tujyane sends a signed ping at once and answers with what your receiver returned. See Account.
The request
Section titled “The request”POST /tujyane/webhooks HTTP/1.1Content-Type: application/jsonUser-Agent: Tujyane-Webhooks/1.0Tujyane-Event-Id: b7f6d2e8-0a9c-4e4b-9f87-2c3d4e5f6a77Tujyane-Event-Type: shipment.deliveredTujyane-Signature: t=1793695189,v1=5f0c1d6a1b2e...{ "id": "b7f6d2e8-0a9c-4e4b-9f87-2c3d4e5f6a77", "type": "shipment.delivered", "createdAt": "2026-11-03T08:39:48.630Z", "mode": "LIVE", "data": { "shipment": { "id": "7d0f3c52-9a4e-4f1b-8c2d-5e6a7b8c9d01", "status": "DELIVERED" } }}data.shipment is the full Shipment object at the time of the event. A ping has data: {}. The list of event types is in Events.
Verify the signature
Section titled “Verify the signature”Tujyane-Signature is t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of the string <t>.<raw body>, keyed with your webhook secret.
- Read the raw request body as bytes. Do not parse it and serialise it again first.
- Compute the HMAC over
t, a dot, and the raw body. Compare it withv1in constant time. - Reject the request if
tis more than 5 minutes from your clock. Tujyane signs each attempt again, so a retry has a newt.
A receiver in Node.js with Express:
import crypto from 'node:crypto';import express from 'express';
const SECRET = process.env.TUJYANE_WEBHOOK_SECRET;const TOLERANCE_SECONDS = 300;
export function isValidSignature(header, rawBody, secret, nowSeconds = Date.now() / 1000) { const parts = header.split(',').map((part) => part.trim().split('=')); const t = Number(parts.find(([name]) => name === 't')?.[1]); if (!Number.isInteger(t) || Math.abs(nowSeconds - t) > TOLERANCE_SECONDS) return false; const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest(); return parts.some(([name, value]) => { if (name !== 'v1' || !value) return false; const given = Buffer.from(value, 'hex'); return given.length === expected.length && crypto.timingSafeEqual(given, expected); });}
const app = express();
app.post('/tujyane/webhooks', express.raw({ type: 'application/json' }), async (req, res) => { const rawBody = req.body.toString('utf8'); if (!isValidSignature(req.get('Tujyane-Signature') ?? '', rawBody, SECRET)) { return res.sendStatus(400); } const event = JSON.parse(rawBody); await saveOnce(event.id, event); res.sendStatus(200);});saveOnce is your code. It stores the event unless an event with that id is already stored. Process the event after you answer.
Answer quickly
Section titled “Answer quickly”Any 2xx answer within 10 seconds acknowledges the event. Anything else is a failure: another status, a redirect (Tujyane does not follow them), a timeout, or a connection error.
Retries
Section titled “Retries”Tujyane retries a failed event on this schedule, counted from the previous attempt:
| Attempt | After the previous attempt |
|---|---|
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 and later | 6 hours |
Each event stops 24 hours after it was created, with a last attempt at that mark: 9 attempts at most. Then the event is FAILED. Expect up to one more minute of delay on each retry. Ask Tujyane to resend a FAILED event.
Order and duplicates
Section titled “Order and duplicates”- The events of one Shipment arrive in the order they happened. While an event is waiting or retrying, the later events of that Shipment wait behind it. Events of different Shipments do not wait for each other.
- Because each event stops 24 hours after it was created, an event that waited behind a long outage may get only one attempt.
- The same event can arrive more than once, for example when your answer is lost. Use
id(also inTujyane-Event-Id) to ignore a repeat. - Tujyane can add event types. Answer
2xxto types you do not know, and ignore them.
Find what you missed
Section titled “Find what you missed”GET /shipments/:id/events lists the events of one Shipment with their webhook state: PENDING, PROCESSING, DELIVERED, FAILED, or SKIPPED (no webhook URL was set at the time). It shows the type and time of each event, not the Shipment as it was. For the current state, read GET /shipments/:id. See Shipments.

