Webhooks

Receive signed notifications when verification and assurance events occur.

Events and envelope

Acretix sends these event types:

verification.completed
verification.flagged
verification.failed
assurance.threshold_breach

Webhook payload version: 1. Every envelope contains these keys: version, id, type, api_version, created, data.

The X-Acretix-Signature header has the form t=<unix>,v1=<hex>. Its v1 value is an HMAC-SHA256 over t, a dot, and the raw body (t.raw body). Pass the raw body exactly as received: do not parse, reserialize, or otherwise transform it before verification.

The default timestamp tolerance is 300 seconds.

Verification can reject a webhook for one of these reasons:

Reasons a webhook is rejected
Code	What it means	What to do
`missing_header`	The `X-Acretix-Signature` header is not on the request.	Check that your framework or proxy passes the `X-Acretix-Signature` header through to your handler.
`malformed_header`	The `X-Acretix-Signature` header is not of the form `t=<unix>,v1=<hex>`.	Pass the `X-Acretix-Signature` header value exactly as received.
`timestamp_outside_tolerance`	The signed timestamp is more than 300 seconds from your server's time.	Check the receiving server's clock.
`signature_mismatch`	The `v1` signature does not match the body and your secret.	Pass the raw request body exactly as received, not a parsed and re-serialised body, and check the webhook secret.

TypeScript

import { AcretixWebhookError, verifyWebhook } from '@acretix-verify/sdk';

try {
  // verifyWebhook(rawBody, signatureHeader, secret, options?)
  const event = verifyWebhook(rawBody, signatureHeader, secret);
  // Process event only after recording event.id for de-duplication.
} catch (error) {
  if (error instanceof AcretixWebhookError) {
    // Reject an invalid webhook.
  }
  throw error;
}

Python

from acretix_verify import AcretixWebhookError, verify_webhook

try:
    event = verify_webhook(
        raw_body,
        signature_header,
        secret,
        tolerance_seconds=300,
        now=None,
    )
    # Process event only after recording event.id for de-duplication.
except AcretixWebhookError:
    # Reject an invalid webhook.
    pass

Retries and duplicate deliveries

Respond with a 2xx status quickly. Each delivery attempt waits at most 5 seconds for your reply.

A delivery is retried after a 5xx reply, a network failure, no reply within 5 seconds, or any other reply that is neither 2xx nor 4xx. A 4xx reply, or an address Acretix refuses to send to, ends the delivery at once and is not retried.

There are at most 5 attempts in all. The waits before each retry are 1 minute, 5 minutes, 30 minutes, 2 hours.

De-duplicate on the envelope id. It is the same for every delivery of one event about one verification, including retries.

Per-request callback