Webhooks overview

Webhooks are how Zquence notifies your backend when something changes — KYC submissions, provider verification outcomes, account lifecycle transitions, document reviews, case locks, and tenant updates.

How webhooks work

Add a webhook endpoint

Go to Developers → Webhooks in the dashboard and add your backend HTTPS URL.

Choose events to subscribe to

Subscribe to exact events like kyc.provider.completed, namespace wildcards like kyc.* or account.*, or * for everything.

Zquence sends a signed POST request

Each delivery is an HTTPS POST with a JSON body and signed X-Webhook-* headers for verification.

Your backend verifies and responds

Verify the signature, enqueue the work, and return any 2xx status within 10 seconds.

Delivery format

Every delivery is an HTTPS POST with the following headers:

Header	Example value	Purpose
`Content-Type`	`application/json`	Body encoding.
`User-Agent`	`Zquence-Webhooks/1.0`	Identifies the sender.
`X-Webhook-Timestamp`	`1745311982`	Unix timestamp used in the signature.
`X-Webhook-Signature`	`sha256=b8a7e1c4...`	HMAC-SHA256 signature — verify before trusting the payload.
`X-Webhook-Signature-Version`	`v1`	Signature algorithm version.
`X-Zquence-Event`	`kyc.provider.completed`	Convenience routing header — mirrors `body.type`.
`X-Zquence-Webhook-Id`	`evt_0b3e2d90...`	Unique event ID — use for idempotency.

Example delivery

POST /webhooks/zquence HTTP/1.1
Content-Type: application/json
User-Agent: Zquence-Webhooks/1.0
X-Webhook-Timestamp: 1749289961
X-Webhook-Signature: sha256=b8a7e1c4d2f3e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0
X-Webhook-Signature-Version: v1
X-Zquence-Event: kyc.provider.completed
X-Zquence-Webhook-Id: evt_0b3e2d90d18048eaa913704cd52937b9

{
  "id": "evt_0b3e2d90d18048eaa913704cd52937b9",
  "type": "kyc.provider.completed",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "environmentType": "live",
  "data": {
    "userId": "6a25cdac36bc6230704b5b59",
    "provider": "onfido",
    "status": "complete",
    "workflowRunId": "5d9b5f73-4b43-4d54-8c2c-86c0f8a53f4f"
  },
  "createdAt": "2026-06-07T09:12:41.208Z"
}

Every event envelope includes environmentId and environmentType so you can distinguish live from sandbox traffic without inspecting the payload.

Handler pattern

Your webhook handler should be intentionally minimal:

Read the raw request body (before any JSON parsing).
Verify X-Webhook-Signature using X-Webhook-Timestamp and your endpoint secret.
Return 200 OK immediately.
Enqueue the event for asynchronous processing.

Never trust a webhook payload before signature verification succeeds. Never do slow work (database writes, API calls) before returning 2xx — you have 10 seconds before Zquence treats the delivery as failed.

Node.js (Express)

app.post(
  "/webhooks/zquence",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let event;
    try {
      event = verifyWebhook(
        req.body,
        req.headers["x-webhook-timestamp"] as string,
        req.headers["x-webhook-signature"] as string,
        process.env.ZQUENCE_WEBHOOK_SECRET!,
      );
    } catch {
      return res.status(400).send("Invalid signature");
    }

    await queue.push(event);   // enqueue — do not process inline
    return res.sendStatus(200);
  },
);

Signing secrets

Each endpoint has exactly one signing secret:

Provide your own secret when creating the endpoint, or leave it blank and Zquence auto-generates a whsec_... value.
The secret is scoped to that endpoint only — different endpoints use different secrets.
Rotating the secret takes effect immediately on the next delivery.

Store the secret in your backend secrets manager. Never expose it to a browser or include it in client-side code.

Idempotency and duplicates

Retries and manual replays can produce duplicate deliveries for the same event. Deduplicate on event.id before processing:

Node.js

const firstTime = await redis.set(
  `zquence:event:${event.id}`,
  "1",
  { NX: true, EX: 7 * 24 * 3600 },   // 7-day TTL
);

if (firstTime !== "OK") {
  return res.sendStatus(200);  // already handled — acknowledge and skip
}

await enqueue(event);
return res.sendStatus(200);

Retries

If your endpoint returns a non-2xx response or exceeds the 10-second timeout, Zquence marks that attempt as failed and schedules a retry using exponential backoff. Default delivery schedule (3 retries, 4 attempts total):

Attempt	Delay from previous
1	Immediate
2	2 seconds
3	4 seconds
4	8 seconds

The number of retries is configurable per environment. The values above reflect the platform default (DEFAULT_WEBHOOK_RETRIES = 3).

After all attempts are exhausted, the delivery is marked failed. You can replay failed deliveries manually from the dashboard or via the API — see Retries.

Manual replay

Zquence stores every delivery and supports on-demand replay. Use this to recover from outages, reprocess missed events, or resync a downstream system. Replay behavior:

Scoped to the tenant triggering the replay.
Re-delivers the original payload to your configured endpoint — it does not re-emit the event from source.
Does not alter historical records inside Zquence.
Filterable by environment, endpoint, event type, status, and date range.

Receiver response codes

Your response	Zquence behaviour
`2xx` (200–299)	Success — delivery complete, no retry.
`4xx` / `5xx`	Failed — retried with backoff while attempts remain.
Timeout (> 10 s)	Failed — retried with backoff while attempts remain.
Connection refused	Failed — retried with backoff while attempts remain.

Even 400 Bad Request and 403 Forbidden are treated as failures and trigger a retry. Your handler should return 200 for events it does not recognise, rather than returning a 4xx.

Local development

Use a tunnel to receive webhooks on your local machine:

ngrok http 3000

https://abc123.ngrok-free.app/webhooks/zquence

Set the corresponding ZQUENCE_WEBHOOK_SECRET environment variable locally to the secret shown in the dashboard for that endpoint.

Next steps

Verify signatures

Reference verification handlers for Node.js, Python, and Go.

Event catalog

Every supported event with payload schemas and examples.

Retries

Retry timing, timeouts, and manual replay.

Best practices

Patterns to keep your integration fast and resilient.

Start here

Integration basics

Webhooks overview

How webhooks work

Delivery format

Example delivery

Handler pattern

Signing secrets

Idempotency and duplicates

Retries

Manual replay

Receiver response codes

Local development

Next steps

Verify signatures

Event catalog

Retries

Best practices

​How webhooks work

​Delivery format

​Example delivery

​Handler pattern

​Signing secrets

​Idempotency and duplicates

​Retries

​Manual replay

​Receiver response codes

​Local development

​Next steps

Verify signatures

Event catalog

Retries

Best practices

How webhooks work

Delivery format

Example delivery

Handler pattern

Signing secrets

Idempotency and duplicates

Retries

Manual replay

Receiver response codes

Local development

Next steps