Tirth API · Guide
Webhooks
Tirth sends a webhook to your endpoints at every stage of a booking, from requested or booked to closed, and for declined and cancelled. Each one is signed, so you can tell it came from Tirth.
Endpoints
Manage endpoints with the webhooks:manage scope:
| Call | What it does |
|---|---|
POST /v2/webhook-endpoints | Adds an endpoint: an https URL on port 443, and the event_types it wants (all of them unless you name some) |
GET /v2/webhook-endpoints | Lists your endpoints in this environment |
DELETE /v2/webhook-endpoints/{id} | Switches an endpoint off; its waiting deliveries stop |
POST /v2/webhook-endpoints/{id}/rotate-secret | Gives the endpoint a new signing secret |
GET /v2/webhook-deliveries | The deliveries of the last 30 days, with each attempt's status code and timing |
- Each environment has at most 3 active endpoints. A fourth is
409 endpoint_limit_reached. - A new endpoint's signing secret starts with
whsec_. It is in the answer once and never shown again: store it as you store a key. - The URL must be
httpson port 443 at a public address. Tirth never follows a redirect and never sends to a private network.
curl https://sandbox.api.tirth.com/v2/webhook-endpoints \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/webhooks/tirth" }'Events
The event types are booking.requested, booking.booked, booking.declined, booking.assigned, booking.scheduled, booking.performed, booking.proof_shared, booking.closed and booking.cancelled.
{
"id": "evt_01JE5KD6F8H0K2M4P6R8T0V2X4",
"type": "booking.assigned",
"created_at": "2026-12-05T10:12:00+05:30",
"api_version": "2026-11-03",
"data": {
"booking_id": "ord_01JE5KC5E7G9J1M3P5R7T9V1X3",
"partner_reference": "ORD-2026-000123",
"status": "assigned",
"version": 3,
"occurred_at": "2026-12-05T10:12:00+05:30"
}
}A webhook carries IDs and the status only, never personal data. Read the booking with GET /v2/bookings/{id} before you act on it. Each change bumps the booking's version: ignore an event whose version is lower than one you have already seen, since deliveries can arrive out of order or more than once. Use the event's id to keep each one once.
The signature
Every delivery carries a Tirth-Signature header:
Tirth-Signature: t=1796375100,v1=7ac20f7eac2d9d05750b84539b5b338a6606767bf7ba4db85bd9ad80e75c5e69tis when it was signed, in Unix seconds.v1is the HMAC-SHA256, in hex, oft, a full stop and the raw body, keyed with the endpoint's wholewhsec_secret.- Reject an event whose
tis more than 5 minutes from your clock. - Compare in constant time, and check the raw bytes you received, before any JSON parsing.
The test vector: with the secret whsec_test_0123456789, t = 1796375100 (2:35 PM IST, Fri 4 Dec 2026) and the body {"id":"evt_test","type":"booking.booked"}, v1 is 7ac20f7eac2d9d05750b84539b5b338a6606767bf7ba4db85bd9ad80e75c5e69. A receiver that sees that t 6 minutes later must reject it.
Verifying in Node
import crypto from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
export function verifyTirthSignature(header, rawBody, secret, now = Date.now()) {
const pairs = header.split(',').map((part) => part.trim().split('='));
const times = pairs.filter(([key]) => key === 't').map(([, value]) => value);
const signatures = pairs.filter(([key]) => key === 'v1').map(([, value]) => value);
if (times.length !== 1 || !/^\d+$/.test(times[0]) || signatures.length === 0) return false;
const t = Number(times[0]);
if (Math.abs(Math.floor(now / 1000) - t) > TOLERANCE_SECONDS) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`, 'utf8').digest();
return signatures.some((signature) => {
const given = Buffer.from(signature, 'hex');
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
}Read the body as text before parsing it:
import { createServer } from 'node:http';
createServer(async (request, response) => {
const chunks = [];
for await (const chunk of request) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString('utf8');
const header = request.headers['tirth-signature'] ?? '';
if (!verifyTirthSignature(header, rawBody, process.env.TIRTH_WEBHOOK_SECRET)) {
response.writeHead(400).end();
return;
}
const event = JSON.parse(rawBody);
// Keep event.id once, then read GET /v2/bookings/{event.data.booking_id} before acting.
response.writeHead(200).end();
}).listen(8080);Verifying in Python
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 5 * 60
def verify_tirth_signature(header: str, raw_body: bytes, secret: str, now: float | None = None) -> bool:
pairs = [part.strip().split("=", 1) for part in header.split(",")]
times = [pair[1] for pair in pairs if len(pair) == 2 and pair[0] == "t"]
signatures = [pair[1] for pair in pairs if len(pair) == 2 and pair[0] == "v1"]
if len(times) != 1 or not times[0].isdigit() or not signatures:
return False
t = int(times[0])
if abs((time.time() if now is None else now) - t) > TOLERANCE_SECONDS:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, signature) for signature in signatures)Rotating the secret
POST /v2/webhook-endpoints/{id}/rotate-secret answers the new secret once. For the next 24 hours, each delivery carries a v1 for each secret, the new one first:
Tirth-Signature: t=1796375100,v1=<signed with the new secret>,v1=<signed with the old secret>Both verifiers above accept a header when any v1 matches, so deploy the new secret within those 24 hours and nothing is missed.
Delivery and retries
- Answer with any
2xxonce you have stored the event. Anything else, or no answer, counts as a failure. - A failed delivery is tried again with backoff for 72 hours.
- An endpoint that keeps failing for 5 days is switched off. Its deliveries stay in
GET /v2/webhook-deliveriesfor 30 days, and the change feed,GET /v2/booking-changes, still has every change: see Bookings and their lifecycle.
