Webhooks
Event payloads, signature verification, retries and delivery rules for EZQR webhooks.
Webhooks send an HTTP POST to your endpoint when something happens in your workspace. Add endpoints in Settings → Webhooks, or subscribe programmatically with POST /hooks. Webhooks are on the Pro and Max plans.
Events
| Event | Sent when |
|---|---|
qr.scanned | A person scans a dynamic QR code. Bots and link previews are excluded |
qr.created | A QR code is created |
qr.updated | A QR code is edited |
qr.deleted | A QR code is deleted |
qr.destination_down | A dynamic code's destination stops responding |
qr.destination_recovered | A dynamic code's destination is reachable again |
lead.created | A lead form, lead-gated QR code or business card exchange is submitted |
card.viewed | A digital business card is opened |
The full schema of each payload is in the webhook events reference.
Payload
Every event has the same envelope:
{
"id": "evt_5b0f1f3e-1c3a-4c86-9f0e-7c3f7f1b2a90",
"type": "qr.scanned",
"createdAt": "2026-10-12T09:00:00.000Z",
"workspaceId": "org_1c9d",
"data": {
"qrCode": { "id": "6f0c3c1e-…", "name": "Spring menu", "shortCode": "k3x9QpL" },
"totalScans": 128,
"scan": {
"device": "Mobile",
"os": "iOS",
"browser": "Safari",
"country": "GB",
"city": "London",
"referrer": null,
"utmSource": "poster",
"utmMedium": "print",
"utmCampaign": "spring"
}
}
}Each request also carries these headers:
| Header | Value |
|---|---|
EZQR-Signature | t={timestamp},v1={signature}, with a second v1 for 24 hours after a secret rotation |
EZQR-Event | The event type, for example qr.scanned |
EZQR-Delivery | A unique id for this delivery |
User-Agent | EZQR-Webhooks/1.0 (+https://ez-qr.com) |
Verify signatures
Each endpoint has a signing secret that starts with whsec_. EZQR signs {timestamp}.{raw body} with HMAC-SHA256 using that secret. Verify it before you trust a request, and reject requests whose timestamp is more than five minutes old.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyEzqrSignature(secret, header, rawBody) {
const parts = header.split(",").map((part) => part.split("="));
const timestamp = Number(parts.find(([key]) => key === "t")?.[1]);
if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) {
return false;
}
const expected = createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest();
return parts
.filter(([key]) => key === "v1")
.some(([, value]) => {
const received = Buffer.from(value, "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
});
}Verify against the raw request body, before any JSON parsing. Re-serialising the JSON changes the bytes and breaks the signature.
Rotate a secret
Choose Rotate secret from the endpoint's menu in Settings → Webhooks. For the next 24 hours, every delivery carries two v1 signatures, one made with the new secret and one with the old secret. Deploy the new secret to your receiver at any point in that window; the verification code above accepts either signature. After 24 hours only the new secret is used.
Respond quickly
Return any 2xx status within 10 seconds. Do slow work, such as calling other APIs, after you respond, for example by putting the event on a queue.
Retries
If your endpoint returns a non-2xx status, times out or can't be reached, EZQR retries the delivery up to 10 times with exponential backoff, starting after about a minute and waiting at most three hours between attempts.
If 20 deliveries in a row fail after all their retries, the endpoint is turned off and you'll see it as disabled in Settings → Webhooks. Turn it back on when your endpoint is fixed. You can also resend any delivery from its delivery history.
Duplicates and ordering
A delivery can arrive more than once, for example when your endpoint processed it but answered too slowly. Use the envelope id to ignore events you've already handled. Events aren't guaranteed to arrive in order, so use createdAt when order matters.
Endpoint requirements
- The URL must be publicly reachable. Private, loopback and internal addresses are rejected.
- Use HTTPS so payloads and signatures are encrypted in transit.