Webhooks and events
Tring tells your system when something happens, by a signed HTTPS POST to an address you register. A notice is thin: what happened, when, to which business, and the identifiers. Read the details with your key; that read is also how you know the notice told the truth.
The events
type | When | data |
|---|---|---|
document.issued | A document was issued, through the API or in the portal | documentId |
document.cancelled | A document was cancelled | documentId |
draft.confirmed | Your draft became a document | draftId, documentId |
draft.expired | Your draft passed its time unconfirmed | draftId |
delivery.opened | The page of a personal link was opened for the first time | documentId, linkId |
delivery.downloaded | A file was taken through a link: the original the first time | documentId, linkId, deliveryId |
consent.changed | A customer gave or withdrew consent | customerKey |
allocation.received, allocation.held, allocation.failed | An allocation number arrived, was held, or was refused | documentId |
transmission.status_changed, transmission.failed | A transmission of the uniform file changed or failed | exportId |
issuer.activated, issuer.granted, issuer.revoked | A business was activated, granted your system, or withdrew it | |
endpoint.test | Sent by POST /v1/webhook-endpoints/{id}/test | endpointId |
{
"id": "0b3c0b6e-35d4-4ab5-9e43-6a3e1f0d6f21",
"object": "event",
"type": "document.issued",
"created": "2026-11-20T09:15:02.418Z",
"environment": "sandbox",
"issuerId": "8d0f4b5e-0c6b-4c1e-9d56-1f3f8f7a2b10",
"data": { "documentId": "d6980f12-1c28-49dd-9449-efde29b023df" }
}Headers: Tring-Signature, Tring-Event-Id, Tring-Event-Type, Tring-Delivery-Id, Tring-Delivery-Attempt. The SDKs type every body (TringWebhookEvent, discriminated by type).
Register an address
const { endpoint, secret } = await tring.createWebhookEndpoint({
url: 'https://example.com/tring/webhook',
eventTypes: ['document.issued', 'delivery.downloaded'], // or ['*']
});
// store `secret` now, like the API key: no later answer holds it
await tring.sendWebhookTest(endpoint.id); // posts an endpoint.test notice at oncecreated = tring.create_webhook_endpoint({
"url": "https://example.com/tring/webhook",
"eventTypes": ["document.issued", "delivery.downloaded"],
})
secret = created["secret"] # store it now: no later answer holds it
tring.send_webhook_test(created["endpoint"]["id"])curl -sS -X POST "$TRING_BASE_URL/v1/webhook-endpoints" \
-H "Authorization: Bearer $TRING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/tring/webhook", "eventTypes": ["document.issued"]}'The address must be https with a public host (the sandbox also allows http and your own machine). Registering, changing, rotating and testing need a key with the scope webhooks; the reads need read. At most 16 addresses.
Check every notice
Tring-Signature is t=<unix seconds>,v1=<hex>. v1 is the lower-case hex HMAC-SHA256 of <t>. followed by the raw body, under your secret (the whole whsec_... string). Refuse a notice whose t is more than 300 seconds from your clock. The SDK helper does all of this, in constant time, and accepts several secrets during a rotation:
// A webhook receiver: check the signature on the raw body, answer 2xx at once, then do the work once per
// event id. Works the same in Express (express.raw({ type: 'application/json' })), Next.js route handlers
// (await request.arrayBuffer()) and edge runtimes.
// Run: TRING_WEBHOOK_SECRET=whsec_... node webhook-handler.mjs
import http from 'node:http';
import { constructWebhookEvent, TringSignatureError } from 'tring-sdk';
// During a rotation put the old and the new secret here: TRING_WEBHOOK_SECRET=old,new
const secrets = (process.env.TRING_WEBHOOK_SECRET ?? '').split(',').filter(Boolean);
const seen = new Set(); // keep this in your database: a notice can arrive more than once
http
.createServer(async (req, res) => {
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
let event;
try {
// the raw bytes: a body parsed and written again would not match the signature
event = await constructWebhookEvent({ payload: Buffer.concat(chunks), headers: req.headers, secret: secrets });
} catch (err) {
res.writeHead(err instanceof TringSignatureError ? 400 : 500).end();
return;
}
res.writeHead(204).end(); // answer within 10 seconds, before the work
if (seen.has(event.id)) return;
seen.add(event.id);
// A notice holds identifiers only: read the details with your key, e.g. tring.getDocument(event.data.documentId)
console.log(event.type, event.data);
})
.listen(Number(process.env.PORT ?? 3000));from tring_sdk import construct_webhook_event, TringSignatureError
# Flask: request.get_data(); Django: request.body; FastAPI: await request.body()
try:
event = construct_webhook_event(request.get_data(), headers=request.headers, secret=[WEBHOOK_SECRET])
except TringSignatureError:
abort(400)
# answer 2xx now; do the work once per event["id"]- Use the raw body, the bytes as they arrived. A body parsed and written again is not the same bytes.
- Answer
2xxwithin 10 seconds, before doing the work. - Keep the event
idand do nothing twice for one id: a notice can arrive more than once, and in any order. - A notice never asks you to issue anything. If you issue because of one, still prepare and confirm under your own Idempotency-Key.
Retries, rotation, the log
A notice not answered 2xx in 10 seconds is tried again after about 1 minute, 5 minutes, 25 minutes, 2 hours, 10 hours, then every 12 hours, for three days. An address that took nothing for three days is switched off; switch it on again with updateWebhookEndpoint(id, { enabled: true }).
rotateWebhookSecret(id, { overlapSeconds: 86400 }) returns a new secret; the old one keeps signing beside it for the overlap, so every notice carries two v1. Put both secrets in your receiver, then remove the old one. { overlapSeconds: 0 } ends a leaked secret at once.
listWebhookDeliveries(endpointId) and getWebhookDelivery(deliveryId) show every try (your status, how long, why it failed); redeliverWebhook(deliveryId) sends one again with the same event id.
Reading events after a gap
Every event meant for your system is also in GET /v1/events, oldest first. Keep the id of the last event you handled and ask for what came after it:
let after = lastHandledEventId;
for (;;) {
const page = await tring.listEvents({ after, limit: 100 });
for (const event of page.items) await handle(event);
if (!page.nextCursor) break;
after = page.items.at(-1).id;
}after = last_handled_event_id
while True:
page = tring.list_events(after=after, limit=100)
for event in page["items"]:
handle(event)
if not page["nextCursor"]:
break
after = page["items"][-1]["id"]Try it locally
The mock sends real signed notices: run npx tring-mock-server, register http://127.0.0.1:3000/ with the handler above running, and issue a receipt from the quickstart.