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
scan.created	Imeacht scanta (ailias do qr.scanned)
workspace.updated	Spás oibre nuashonraithe
webhook.ping	Ping tástála (tríd an gcríochphointe /ping)

Formáid an Phálasta

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

{
  "id": "evt_abc123xyz",
  "type": "qr.scanned",
  "created": "2026-03-15T10:00:00.000Z",
  "data": {
    "code_id": "qr_abc123",
    "short_code": "r7f3Kx",
    "scan_id": "scn_xyz",
    "country": "AT",
    "device_type": "mobile",
    "os": "iOS"
  }
}

Fíorú Sínithe

qr3.app síníonn gach iarratas Webhook le HMAC-SHA256:

X-QR3-Signature: sha256=a1b2c3d4e5f6...

Fíorú a chur i bhfeidhm

Node.js

import crypto from "crypto";

function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  const received = signature.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

// In Express:
app.post("/webhooks/qr3", (req, res) => {
  const signature = req.headers["x-qr3-signature"] as string;
  const valid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.QR3_WEBHOOK_SECRET
  );
  if (!valid) return res.status(401).json({ error: "Invalid signature" });

  const event = req.body;
  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.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.

Logaí Seachadta

GET /v1/webhooks/:id/deliveries

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

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.