Webhooks

Get every scan sent to your own software as it happens. Webhooks are part of Premium.

Adding one

Add an endpoint on the Developers page, or with POST /webhooks. It must use https and be reachable from the internet. Add qr_code_id to hear about one code only. The signing secret is shown once, so keep it safe.

The event

Each scan sends a POST with this body. Link previews and repeat bursts aren’t counted as scans, and IP addresses aren’t included.

{
  "id": "evt_6f1c2e",
  "type": "scan.created",
  "created_at": "2026-11-07T19:42:10.000Z",
  "data": {
    "code": {
      "id": "b3a1…",
      "short_code": "abc123",
      "title": "Dinner menu",
      "type": "menu",
      "tags": ["dining-room"],
      "metadata": { "site": "main" }
    },
    "scan": {
      "device": "mobile",
      "os": "iOS",
      "language": "es",
      "country": "ES",
      "table": { "id": "7d2e…", "name": "Table 12" },
      "destination": "https://example.com/menu",
      "rule": { "type": "time", "label": "Dinner" },
      "unique": true
    }
  }
}

Headers

PikaQR-Signature

The timestamp and signature, explained below

PikaQR-Event

scan.created, or ping for a test

PikaQR-Delivery

A unique id for this delivery, which stays the same across retries

Checking the signature

The signature header looks like t=1794021863,v1=5f8a…. Sign t, a full stop and the raw body with your secret, using HMAC-SHA256, and compare. Refuse old timestamps so a captured request can’t be replayed.

import { createHmac, timingSafeEqual } from 'node:crypto';

// `body` must be the raw request body, before any JSON parsing.
function isFromPikaQR(body, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Delivery and retries

Answer with any 2xx status within 10 seconds. Anything else counts as a failure, and redirects aren’t followed. Failed deliveries are tried again after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours. An event may arrive more than once, so use its id to ignore repeats.

An endpoint that keeps failing is turned off after 20 failed events, and turning it back on gives it a clean slate.

Testing

Use “Send test” on the Developers page, or POST /webhooks/:id/test, to send a ping. Recent attempts and their results are on the same page, and at GET /webhooks/:id/deliveries.

QR code scan webhooks · PikaQR