Webhooks

Webhooks

Le Webhooks, faigheann tú fógraí fíor-ama nuair a tharlaíonn imeachtaí i do spás oibre — m.sh. nuair a scanann duine cód QR.

Webhook a chruthú

POST /v1/webhooks

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

Caution

Ní mór do URLanna Webhook HTTPS a úsáid. Diúltófar do URLanna HTTP.

Freagra

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

Ní sheoltar an secret ar ais ach uair amháin. Coinnigh slán é — tá sé ag teastáil le haghaidh fíorú sínithe.

Cineálacha Imeachtaí

Imeacht	Cur síos
*	Gach imeacht
qr.created	Cód QR cruthaithe
qr.updated	Cód QR nuashonraithe (URL, stádas, clibeanna)
qr.deleted	Cód QR scriosta
qr.scanned	Cód QR scanta
qr.flagged	Cód QR marcáilte mar neamhshábháilte
webhook.ping	Ping tástála (tríd an gcríochphointe /ping)

Note

Tá Webhooks san áireamh ón bplean Pro. Tuairiscíonn qr.scanned scananna de do chuid cóid agus cuairteanna ar Phas Táirge Digiteach tríd an réiteoir; i gcás DPP, iompraíonn data dpp_id, gtin, serial agus lot in ionad code_id agus short_code. Níl aon seoladh IP sna pálastaí.

Formáid an Phálasta

Tá an fhormáid seo ag gach pálasta Webhook:

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

Imeachtaí Cóid: qr.created agus qr.updated

Sna dhá imeacht seo, is é data an cód go díreach mar a sheachadann GET /v1/codes/:id é. Áirítear leis seo appearance, na dathanna atá sábháilte ar an gcód (seasann null don dath dubh nó bán réamhshocraithe):

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

Tá an sampla seo giorraithe. Tá na réimsí go léir ar fáil san API na gCód.

Fíorú Sínithe

qr3.app síníonn gach iarratas Webhook le 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

Fíorú a chur i bhfeidhm

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)

Loighic Atrialach

I gcás earráidí (HTTP >= 300 nó teorainn ama), déanann qr3.app iarracht an seachadadh a dhéanamh arís:

Iarracht	Moill
1	Láithreach
2	1 nóiméad
3	5 nóiméad

Tar éis 10 dteip as a chéile, díchonófar an Webhook go huathoibríoch.

Ráthaíocht Seachadta

Seachadann qr3.app uair amháin ar a laghad, ní go díreach uair amháin. Dá bhrí sin, féadann an t-imeacht céanna teacht ar do chríochphointe níos mó ná uair amháin: mar iarracht eile tar éis earráide nó mar athdhéanamh ar iarracht a seoladh cheana.

• Aithin dúbailtí le id an payload (evt_…). Baineann sé leis an imeacht agus fanann sé mar an gcéanna i ngach iarracht agus i ngach athdhéanamh. Sainaithníonn X-QR3-Delivery an iarracht aonair: tá an luach céanna ag athdhéanamh na hiarrachta sin, agus luach nua ag iarracht nua. Admhaigh id atá ar eolas agat cheana le 2xx, ní le 4xx: áirítear 4xx mar iarracht theip, agus tar éis 10 dteip as a chéile, díchonófar an Webhook go huathoibríoch.
• Cuireann glanadh laethúil iarracht atá fós pending uair an chloig tar éis í a chruthú (mar shampla toisc go bhfuil a teachtaireacht sa scuaine caillte) ar failed; fanann status_code agus response_time_ms ar null. Ní earráid de do chuid críochphointe é seo agus ní áirítear i measc na 10 dteip as a chéile é. Stórálann an lóg an téacs Delivery was not completed in time — closed by cleanup dó; ní thugann an críochphointe do logaí seachadta ar ais é. Níl an dúnadh buan: má shroicheann an teachtaireacht ceann scríbe ina dhiaidh sin, seachadtar í agus cuireann a fíorthoradh an téacs sin ina áit.

Logaí Seachadta

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

Coinnítear iarrachtaí seachadta ar feadh 90 lá (an lá UTC reatha móide an 89 lá roimhe sin) agus scriostar go huathoibríoch iad ina dhiaidh sin. Chomh maith leis na réimsí a thaispeántar, stórálann an lóg payload an imeachta agus an chéad kilobyte (1 KB) de fhreagra an chríochphointe; ní thugann an críochphointe seo ceachtar acu ar ais.

Ping Tástála

Tástáil Webhook láithreach:

POST /v1/webhooks/:id/ping

Seolann sé seo imeacht webhook.ping chuig do URL críochphointe.