Webhooks

Webhooks

Med webhooks modtager du realtidsnotifikationer, når der sker hændelser i dit workspace — f.eks. når en QR-kode scannes.

Opret webhook

POST /v1/webhooks

{
  "url": "https://example.com/webhooks/qr3",
  "events": ["qr.scanned", "qr.created"],
  "secret": "my-secret-key-min-16-chars"
}

Caution

Webhook-URL’er skal bruge HTTPS. HTTP-URL’er afvises.

Response

{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/qr3",
  "events": ["qr.scanned", "qr.created"],
  "is_active": true,
  "secret": "my-secret-key-min-16-chars",
  "secret_hint": "my-s…",
  "created_at": "2026-03-15T10:00:00.000Z"
}

Note

secret returneres kun én gang. Opbevar det sikkert — det er nødvendigt til signaturverifikation.

Eventtyper

Event	Beskrivelse
*	Alle events
qr.created	QR-kode oprettet
qr.updated	QR-kode opdateret (URL, status, tags)
qr.deleted	QR-kode slettet
qr.scanned	QR-kode scannet
qr.flagged	QR-kode markeret som usikker
webhook.ping	Test-ping (via /ping-endpoint)

Note

Webhooks er inkluderet fra Pro-abonnementet. qr.scanned rapporterer scanninger af dine koder og besøg på et digitalt produktpas via resolveren; for et DPP indeholder data dpp_id, gtin, serial og lot i stedet for code_id og short_code. Payloads indeholder ingen IP-adresse.

Payload-format

Alle webhook-payloads har dette format:

{
  "id": "evt_4f0c2a91d7e84b3c9a1f",
  "type": "qr.scanned",
  "created": "2026-03-15T10:00:00.000Z",
  "data": {
    "code_id": "qr_abc123",
    "short_code": "r7f3Kx",
    "scanned_at": "2026-03-15T10:00:00.000Z",
    "country": "AT",
    "device_type": "mobile",
    "os": "iOS",
    "browser": "Safari",
    "language": "de",
    "ab_variant": null,
    "redirected_to": "https://example.com/landing"
  }
}

Kode-events: qr.created og qr.updated

Ved disse to events er data koden nøjagtig som GET /v1/codes/:id returnerer den. Dette inkluderer appearance, de farver, der er gemt på koden (null står for standard sort eller hvid):

{
  "id": "evt_9b2e41c07a5d4f18b3c6",
  "type": "qr.updated",
  "created": "2026-09-28T10:00:00.000Z",
  "data": {
    "id": "qr_abc123",
    "short_code": "r7f3Kx",
    "status": "live",
    "appearance": { "foreground_color": "#1F4E79", "background_color": null },
    "updated_at": "2026-09-28T10:00:00.000Z"
  }
}

Eksemplet er forkortet. Alle felter findes i kode-API’en.

Signaturverifikation

qr3.app signerer hver webhook-anmodning med HMAC-SHA256:

X-QR3-Signature: sha256=a1b2c3d4e5f6...
X-QR3-Event: qr.scanned
X-QR3-Delivery: wdl_abc123
X-QR3-Attempt: 1
User-Agent: qr3-webhooks/1.0

Implementer verifikation

Node.js

import crypto from "crypto";

function verifySignature(
  payload: string,
  signature: string | undefined,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  const expectedBytes = Buffer.from(`sha256=${expected}`);
  const receivedBytes = Buffer.from(signature ?? "");
  return (
    expectedBytes.length === receivedBytes.length &&
    crypto.timingSafeEqual(expectedBytes, receivedBytes)
  );
}

// In Express: verify the raw body — re-serialised JSON breaks the signature.
app.post(
  "/webhooks/qr3",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body.toString("utf8");
    const signature = req.headers["x-qr3-signature"] as string | undefined;
    if (!verifySignature(raw, signature, process.env.QR3_WEBHOOK_SECRET!)) {
      return res.status(401).json({ error: "Invalid signature" });
    }
    const event = JSON.parse(raw);
    console.log(event.type, event.data);
    res.json({ received: true });
  },
);

Python

import hmac
import hashlib

def verify_signature(payload: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    received = (signature or "").removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

Retry-logik

Ved fejl (HTTP >= 300 eller timeout) forsøger qr3.app at levere igen:

Forsøg	Forsinkelse
1	Med det samme
2	1 minut
3	5 minutter

Efter 10 fejl i træk deaktiveres webhooken automatisk.

Leveringsgaranti

qr3.app leverer mindst én gang, ikke præcis én gang. Den samme hændelse kan derfor nå dit endpoint mere end én gang: som nyt forsøg efter en fejl eller som gentagelse af et forsøg, der allerede er sendt.

• Fjern dubletter ved hjælp af id i payloaden (evt_…). Det hører til hændelsen og er det samme ved hvert forsøg og hver gentagelse. X-QR3-Delivery angiver det enkelte forsøg: En gentagelse af det forsøg har samme værdi, et nyt forsøg en ny. Besvar et id, du allerede kender, med 2xx og ikke med 4xx: Et 4xx tæller som et mislykket forsøg, og efter 10 fejl i træk deaktiveres webhooken automatisk.
• Et forsøg, der stadig er pending en time efter oprettelsen (for eksempel fordi dets besked i køen gik tabt), sættes til failed ved en daglig oprydning; status_code og response_time_ms forbliver null. Det er ikke en fejl hos dit endpoint og tæller ikke med blandt de 10 fejl i træk. Loggen gemmer teksten Delivery was not completed in time — closed by cleanup for det; endepunktet for delivery-logs returnerer den ikke. Lukningen er ikke endelig: Hvis beskeden alligevel kommer frem, bliver den leveret, og dens faktiske resultat erstatter teksten.

Delivery-logs

GET /v1/webhooks/:id/deliveries

{
  "data": [
    {
      "id": "wdl_abc123",
      "event_type": "qr.scanned",
      "status": "success",
      "status_code": 200,
      "response_time_ms": 145,
      "attempt": 1,
      "created_at": "2026-03-15T10:00:00.000Z"
    }
  ]
}

Leveringsforsøg opbevares i 90 dage (den aktuelle UTC-dag plus de 89 foregående dage) og slettes derefter automatisk. Ud over de viste felter gemmer loggen hændelsens payload og det første kilobyte (1 KB) af endepunktets svar; dette endepunkt returnerer ingen af delene.

Test-ping

Test en webhook med det samme:

POST /v1/webhooks/:id/ping

Dette sender en webhook.ping-event til din endpoint-URL.