Webhooks

Webhooks

Naudodami webhooks, gausite realaus laiko pranešimus, kai jūsų Workspace įvyksta įvykiai – pvz., kai nuskaitomas QR kodas.

Webhook kūrimas

POST /v1/webhooks

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

Caution

Webhook URL adresai privalo naudoti HTTPS. HTTP URL adresai bus atmetami.

Atsakymas

{
  "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 yra grąžinamas tik vieną kartą. Saugokite jį saugiai – jis reikalingas parašo verifikavimui.

Įvykių tipai

Įvykis	Aprašymas
*	Visi įvykiai
qr.created	QR kodas sukurtas
qr.updated	QR kodas atnaujintas (URL, būsena, žymos)
qr.deleted	QR kodas ištrintas
qr.scanned	QR kodas nuskaitytas
qr.flagged	QR kodas pažymėtas kaip nesaugus
webhook.ping	Bandomasis ping (per /ping galinį tašką)

Note

Webhooks yra įtraukti nuo Pro plano. qr.scanned praneša apie jūsų kodų nuskaitymus ir Skaitmeninio produkto paso apsilankymus per nukreipimo sistemą (resolver); DPP atveju data perduoda dpp_id, gtin, serial ir lot vietoj code_id ir short_code. Payload duomenyse IP adresas nėra pateikiamas.

Payload formatas

Visi webhook payload duomenys yra šio formato:

{
  "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"
  }
}

Kodų įvykiai: qr.created ir qr.updated

Šių dviejų įvykių metu data yra kodas, tiksliai toks, kokį jį grąžina GET /v1/codes/:id. Prie jo priskiriama appearance – kode išsaugotos spalvos (null reiškia standartinę juodą arba baltą):

{
  "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"
  }
}

Pavyzdys yra sutrumpintas. Visi laukai pateikiami kodų API.

Parašo verifikavimas

qr3.app pasirašo kiekvieną webhook užklausą naudodama 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

Verifikavimo įgyvendinimas

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)

Pakartotinių bandymų logika

Klaidų atveju (HTTP >= 300 arba laiko viršijimas) qr3.app bandys pristatyti iš naujo:

Bandymas	Delsa (Delay)
1	Iškart
2	1 minutė
3	5 minutės

Po 10 nesėkmingų bandymų iš eilės webhook bus automatiškai deaktyvuotas.

Pristatymo garantija

qr3.app pristato bent kartą, o ne tiksliai vieną kartą. Todėl tas pats įvykis gali pasiekti jūsų galinį tašką daugiau nei kartą: kaip pakartotinis bandymas po klaidos arba kaip jau išsiųsto bandymo pakartojimas.

• Dublikatus šalinkite pagal id iš payload (evt_…). Jis priklauso įvykiui ir išlieka toks pat kiekvieno bandymo ir kiekvieno pakartojimo metu. X-QR3-Delivery nurodo atskirą bandymą: to bandymo pakartojimas turi tą pačią reikšmę, naujas bandymas — naują. Jau žinomą id patvirtinkite 2xx, o ne 4xx: 4xx skaičiuojamas kaip nesėkmingas bandymas, o po 10 klaidų iš eilės webhook automatiškai deaktyvuojamas.
• Bandymas, kuris praėjus valandai po sukūrimo vis dar yra pending (pavyzdžiui, nes jo pranešimas eilėje pasimetė), kasdienio valymo metu nustatomas į failed; status_code ir response_time_ms lieka null. Tai nėra jūsų galinio taško klaida ir ji neįskaičiuojama į 10 klaidų iš eilės. Žurnale tam išsaugomas tekstas Delivery was not completed in time — closed by cleanup; pristatymo žurnalų galinis taškas jo negrąžina. Uždarymas nėra galutinis: jei pranešimas vis dėlto atkeliauja, jis pristatomas, o tikrasis jo rezultatas pakeičia šį tekstą.

Pristatymo žurnalai

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"
    }
  ]
}

Pristatymo bandymai saugomi 90 dienų (einamoji UTC diena ir 89 ankstesnės dienos), o po to automatiškai ištrinami. Be rodomų laukų, žurnale saugomas įvykio payload ir pirmasis kilobaitas (1 KB) galinio taško atsakymo; šis galinis taškas negrąžina nei vieno, nei kito.

Testinis ping

Išbandykite webhook iškart:

POST /v1/webhooks/:id/ping

Tai išsiųs webhook.ping įvykį į jūsų galinio taško (endpoint) URL.