Webhooks are how Zquence tells your backend that something changed. Examples include a user being invited, KYC completing, or a transaction changing status.

​
How webhooks work

1

You add a webhook URL

Add your backend URL in the dashboard under Developers -> Webhooks.
2

You choose events

Subscribe to exact events like kyc.completed, or event families like kyc.* and transaction.*.
3

Zquence sends HTTPS POST requests

Each delivery includes event headers, a JSON body, and a zquence-signature header.
4

Your backend verifies and responds

Verify the signature with your webhook secret, enqueue the work, and return 2xx within 10 seconds.

​
Example delivery

POST /webhooks/zquence HTTP/1.1
Content-Type: application/json
X-Zquence-Event: kyc.completed
X-Zquence-Webhook-Id: evt_01HX3ZJ...
zquence-signature: t=1745311982,v1=b8a7e1c4...

{
  "id": "evt_01HX3ZJ...",
  "type": "kyc.completed",
  "tenantId": "tnt_01HX3Z8MQW...",
  "data": {
    "userId": "usr_01HX3ZAB...",
    "status": "complete"
  },
  "createdAt": "2026-04-22T10:34:17.000Z"
}

​
Handler pattern

Your webhook handler should be intentionally small:
  1. Read the raw request body.
  2. Verify zquence-signature.
  3. Store or enqueue the event.
  4. Return 200 OK.
  5. Process the event asynchronously.
Do not trust a webhook until the signature is verified. Do not do slow work before returning a 2xx response.

​
Retries and duplicates

If your URL returns a non-2xx response or times out, Zquence retries with backoff for about 24 hours. Because retries can create duplicate deliveries, store event IDs and process each event.id once.
Node.js
if (await alreadyHandled(event.id)) {
  return res.sendStatus(200);
}

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

​
Local development

Use a tunnel to receive webhooks locally: 
ngrok http 3000
Add the generated HTTPS URL in the dashboard, for example: 
https://abc123.ngrok-free.app/webhooks/zquence

​
Next steps

Verify webhooks

Copy framework-specific verification handlers.

Event catalog

See every event type and payload.

Retries

Learn retry timing and replay behavior.

Best practices

Make handlers reliable in production.