Webhooks

1. An owner or admin opens Settings → Integrations and adds a webhook: a name, an https:// URL, and the event types to receive.
2. Kumry asks them to confirm with multi-factor authentication, because the endpoint will receive the organisation's data.
3. Kumry shows the signing secret once. It starts with whsec_. Store it with your other secrets; Kumry keeps it encrypted and cannot show it again. You can rotate it at any time.

The URL must be HTTPS and must resolve to a public address. Kumry checks the address again when it delivers and does not follow redirects.

Each delivery is a POST with a JSON body and these headers:

{
  "id": "6f1c2a8e-…",                    // same as the kumry-event-id header
  "type": "invoicing.invoice.paid",
  "createdAt": "2026-10-01T03:12:45.120Z",
  "tenantId": "…",                       // your organisation
  "attempt": 1,
  "data": { … }                          // the event's details
}

The kumry-signature header holds a Unix timestamp t and a signature v1. The signature is the hex HMAC-SHA256, keyed with your signing secret, of the timestamp, a full stop, and the raw request body: {t}.{body}.

1. Read the raw body before parsing it; re-serialised JSON will not match.
2. Reject the request if the timestamp is more than five minutes from your clock.
3. Compute the HMAC and compare it to v1 in constant time.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received (a string, before JSON.parse)
export function verifyKumrySignature(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    (header ?? '').split(',').map((part) => part.trim().split('=')),
  );
  const timestamp = Number(parts.t);
  if (!Number.isSafeInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('hex');
  const received = String(parts.v1 ?? '');
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Answer with any 2xx status within 10 seconds to acknowledge the delivery. Do the real work after you respond. Anything else, including a timeout or a redirect, counts as a failed attempt.

After a failed attempt, Kumry tries again after:

1. 2. 30 seconds
2. 3. 2 minutes
3. 4. 10 minutes
4. 5. 1 hour
5. 6. 6 hours

If the sixth attempt fails, the delivery is marked dead and not retried. If an endpoint fails 20 times in a row, Kumry disables that webhook and records why; an owner or admin can re-enable it once the endpoint is fixed. The delivery history for each webhook is in Settings → Integrations.

Because an event can arrive more than once (for example if your endpoint processed it but timed out), use kumry-event-id to skip events you have already handled.