Webhooks

Webhooks push events to your endpoint as they happen. Three events are available today: qrcode.created, qrcode.destination_changed, and qrcode.archived — fired whether the change came from the dashboard or the API. Configure https endpoints and pick their events in Dashboard → Webhooks (Business and Enterprise).

Delivery

Events are POSTed as JSON. Your endpoint has ten seconds to respond with a 2xx; anything else is retried up to five times with exponential backoff (after roughly 1, 4, 16, and 60 minutes). Retries resend the identical payload, so make your handler idempotent.

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Cue-Event: qrcode.destination_changed
X-Cue-Signature: sha256=5f8c2a...e91b

{
  "event": "qrcode.destination_changed",
  "createdAt": 1751500800000,
  "data": {
    "id": "jd7f2k9qmx04v5gz1nwe8c3ht",
    "name": "Spring menu — window sticker",
    "destination": "https://example.com/menu/summer",
    "version": 3
  }
}

Event payloads

• qrcode.created — data carries id, name, kind, and shortCode.
• qrcode.destination_changed — data carries id, name, the new destination, and its version number.
• qrcode.archived — data carries id and name.

Verifying signatures

Every delivery is signed with your endpoint's secret (shown once as whsec_... when you create the endpoint). The X-Cue-Signature header is sha256= followed by the hex HMAC-SHA256 of the raw request body. Recompute it over the exact bytes you received — before any JSON parsing — and compare with a constant-time check.

import { createHmac, timingSafeEqual } from "node:crypto"

function verify(header, rawBody, secret) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  return (
    header.length === expected.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(header))
  )
}