Webhooks

QRlumo can push scan events and code lifecycle changes to any HTTPS endpoint in real time — no polling required.

Setting up a webhook

1. Go to Workspace → Settings → Webhooks
2. Click Add endpoint
3. Enter your HTTPS URL
4. Select the event types you want to receive
5. Save — QRlumo sends a test ping immediately

Event types

Event	Trigger
qrcode.scanned	A QR code is scanned
qrcode.created	A new code is created
qrcode.updated	A code's destination or settings change
qrcode.deleted	A code is deleted
workspace.member_added	A team member joins the workspace

Payload format

All events share a common envelope:

{
  "id": "evt_abc123",
  "event": "qrcode.scanned",
  "createdAt": "2026-06-10T10:00:00Z",
  "workspaceId": "ws_xyz",
  "data": { ... }
}

qrcode.scanned payload

{
  "id": "evt_abc123",
  "event": "qrcode.scanned",
  "createdAt": "2026-06-10T10:00:00Z",
  "workspaceId": "ws_xyz",
  "data": {
    "qrcodeId": "qr_789",
    "qrcodeName": "spring_packaging",
    "scannedAt": "2026-06-10T09:59:58Z",
    "country": "CN",
    "device": "iOS",
    "browser": "Safari",
    "ip": "203.0.113.5",
    "referrer": null
  }
}

Verifying signatures

Every request includes a X-QRlumo-Signature header — an HMAC-SHA256 digest of the raw request body, signed with your endpoint's secret.

import crypto from 'crypto';

function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Always verify the signature before processing a webhook payload.

Retry policy

QRlumo expects a 2xx response within 10 seconds. If the endpoint times out or returns a non-2xx status, QRlumo retries with exponential back-off:

Attempt	Delay
1	Immediate
2	1 minute
3	10 minutes
4	1 hour
5	24 hours

After 5 failed attempts, the event is marked as failed and delivery stops. Failed events are visible in the webhook dashboard.

Webhook limits by plan

Plan	Endpoints	Events / month
Free	3	5,000
Pro	10	50,000
Team	50	500,000
Business	200	Unlimited