Developers
Webhooks
Receive signed HTTPS events, verify them, and rely on automatic retries. Events, payload, signature checks in Node and Python, and delivery rules.
Setting one up
An organization admin opens Settings → Integrations → Webhooks, enters an HTTPS endpoint, chooses events and copies the signing secret (whsec_…, shown once; you can replace it at any time with “New secret”, with or without an overlap; see rotating the secret). Test sends a signed test event so you can check your receiver before real events arrive.
Events
| Event | Sent when |
|---|---|
| agent.status_changed | An agent’s status changed (working, break, AUX, offline…) |
| break.overage | A break or meal ran past its scheduled time |
| exception.created | A new exception was detected |
| exception.resolved | An exception was resolved or excused |
| schedule.published | A schedule was published |
| interaction.recorded | A ticket, conversation or call was recorded for an agent |
Payload and headers
{
"id": "evt-id",
"type": "interaction.recorded",
"createdAt": "2026-10-07T01:14:00.000Z",
"organizationId": "…",
"data": { "employeeId": "…", "kind": "ticket_replied", "source": "zendesk", … }
}| Header | Value |
|---|---|
| TINIUN-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256>[,v1=<hex>]; a second v1 is present only while a secret rotation overlap is open |
| TINIUN-Event | The event type |
| TINIUN-Delivery | Id of this delivery (same across retries); use it to de-duplicate |
| TINIUN-Replayed-From | Only on a replayed delivery: the id of the delivery it repeats |
Verifying the signature
The header is versioned: v1 is the hex HMAC-SHA256, keyed with your signing secret, of the text <t>.<raw request body>. A future scheme would appear as v2 next to it, so ignore entries you don’t know. Use the raw body bytes before any JSON parsing, compare in constant time, accept the request if any v1 matches, and reject timestamps more than 5 minutes old: that window is what stops someone replaying a captured request later. Keep the check even if you also de-duplicate on TINIUN-Delivery.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, rawBody, header, toleranceSec = 300) {
const entries = header.split(',').map((p) => p.trim().split('='));
const t = Number(entries.find(([k]) => k === 't')?.[1]);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'));
return entries.some(([k, v]) => {
if (k !== 'v1' || !v) return false;
const got = Buffer.from(v);
return got.length === expected.length && timingSafeEqual(got, expected);
});
}import hmac, hashlib, time
def verify(secret: str, raw_body: bytes, header: str, tolerance=300) -> bool:
entries = [p.strip().split("=", 1) for p in header.split(",")]
t = next((v for k, v in entries if k == "t"), None)
if t is None or abs(time.time() - int(t)) > tolerance:
return False
signed = t.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return any(k == "v1" and hmac.compare_digest(expected, v) for k, v in entries)Rotating the secret
Choose New secret on a webhook (or POST /admin/webhooks/:id/rotate-secret with { "overlapHours": 24 }, 0 to 168). Without an overlap the old secret stops working immediately. With one, both secrets are valid until the window ends: every delivery carries two v1 signatures and the verifier above accepts either, so you can deploy the new secret at your own pace and nothing is dropped. Rotate again, or choose no overlap, to end the window early.
Delivery and retries
- Answer with any
2xxwithin 8 seconds. Anything else, a timeout or a connection error counts as a failure. - Failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h (six attempts over about nine hours), then marked failed. The delivery log under each webhook shows status, attempts and the last error for seven days.
- Delivery is at least once, not in strict order. De-duplicate on
TINIUN-Deliveryor the eventid. - Redirects are not followed. Endpoints must be HTTPS and must not resolve to private, loopback or link-local addresses; TINIUN checks this again each time it connects.
- Events are sent for the organization that owns the webhook only, and carry identifiers and figures, not free-text notes.
Replaying a delivery
If your receiver was down or lost an event, open the webhook’s delivery log and choose Send again (or POST /admin/webhooks/:id/deliveries/:deliveryId/replay). TINIUN sends the same event and payload again as a new delivery with its own TINIUN-Delivery id, a fresh timestamp and signature, and the TINIUN-Replayed-From header. The event id in the body stays the same, so de-duplicate on it if you must not process an event twice. Only deliveries from the last seven days can be replayed.
Filtering by team
A webhook can be limited to some teams when you create it (teamIds). It then only receives events that belong to one of those teams; events that belong to no team are not sent to a team-filtered webhook. Leave it empty for everything.
See it with your own scenarios
A 30-minute walkthrough with our team, tailored to your operation.
Book a demo
