intouch Webhooks: Delivery Events, Signing & Retries

Webhooks push delivery and engagement events from intouch to your endpoint as they happen — signed with HMAC-SHA256, retried up to six times with backoff — so your systems stay current without polling traceTransactionId. This page covers registering endpoints, verifying signatures, and the handler behaviour that survives real-world failure.

Last reviewed: 22 August 2026.

Managing webhook endpoints

Webhook endpoints are managed through the API itself:

Your endpoint must be HTTPS and should return a 2xx quickly — do the real processing async (queue the payload, ack immediately). Anything else is treated as a delivery failure and retried.

Signature verification

Every delivery is signed with HMAC-SHA256 using your webhook secret. Verify before trusting the payload:

const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Two rules that prevent the classic verification bugs: compute the HMAC over the raw request body bytes (not the re-serialised JSON — key ordering will burn you), and use a constant-time comparison.

Retry behaviour

Failed deliveries (non-2xx, timeout, connection refused) are retried up to 6 attempts with 30-second backoff. Design consequences:

• Handlers must be idempotent. A retry after a timeout can mean the same event arrives twice — deduplicate on the event's transaction ID (transId / your tracking_id), not on receipt.
• Ordering isn't guaranteed under retry. A "delivered" event can arrive after a later engagement event if the first delivery failed. Treat events as state updates keyed by transaction, not as an ordered log.
• After the final retry the event is not redelivered — reconcile gaps by tracing the transaction via POST /traceTransactionId.

Handler checklist

1. Verify the HMAC signature against the raw body.
2. Return 200 immediately; process from a queue.
3. Deduplicate on transaction ID.
4. Upsert state rather than assuming event order.
5. Alert on sustained signature failures — that's either a secret rotation you missed or someone probing your endpoint.

The commercial overview of the webhook/API product sits at /products/api-webhook-integration; the API overview covers auth and the endpoints these events originate from.