Tring for developers עברית

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

typeWhendata
document.issuedA document was issued, through the API or in the portaldocumentId
document.cancelledA document was cancelleddocumentId
draft.confirmedYour draft became a documentdraftId, documentId
draft.expiredYour draft passed its time unconfirmeddraftId
delivery.openedThe page of a personal link was opened for the first timedocumentId, linkId
delivery.downloadedA file was taken through a link: the original the first timedocumentId, linkId, deliveryId
consent.changedA customer gave or withdrew consentcustomerKey
allocation.received, allocation.held, allocation.failedAn allocation number arrived, was held, or was refuseddocumentId
transmission.status_changed, transmission.failedA transmission of the uniform file changed or failedexportId
issuer.activated, issuer.granted, issuer.revokedA business was activated, granted your system, or withdrew it
endpoint.testSent by POST /v1/webhook-endpoints/{id}/testendpointId
A notice
{
  "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

js
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 once

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:

examples/js/webhook-handler.mjs
// 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));
  1. Use the raw body, the bytes as they arrived. A body parsed and written again is not the same bytes.
  2. Answer 2xx within 10 seconds, before doing the work.
  3. Keep the event id and do nothing twice for one id: a notice can arrive more than once, and in any order.
  4. 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:

js
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;
}

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.