Skip to content

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.

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 mode in 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.

POST /tujyane/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Tujyane-Webhooks/1.0
Tujyane-Event-Id: b7f6d2e8-0a9c-4e4b-9f87-2c3d4e5f6a77
Tujyane-Event-Type: shipment.delivered
Tujyane-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.

Tujyane-Signature is t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of the string <t>.<raw body>, keyed with your webhook secret.

  1. Read the raw request body as bytes. Do not parse it and serialise it again first.
  2. Compute the HMAC over t, a dot, and the raw body. Compare it with v1 in constant time.
  3. Reject the request if t is more than 5 minutes from your clock. Tujyane signs each attempt again, so a retry has a new t.

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.

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.

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.

  • 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 in Tujyane-Event-Id) to ignore a repeat.
  • Tujyane can add event types. Answer 2xx to types you do not know, and ignore them.

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.