Recept

Számlafeldolgozási státuszok szinkronizálása

A saját rendszeredben tükrözni akarod, hol tart egy számla a QUiCK feldolgozási pipeline-ban — near-real-time.

Expert~45 perc5 lépés

Előfeltételek

Backend, ami publikus HTTPS endpointot tud fogadni
Adatbázis, ahol a számla-státuszt tárolod
Adminban feltöltött webhook titkos kulcs

1. Webhook regisztrálása

Az adminban add meg a fogadó URL-t és mentsd el a titkot. Ezt fogod használni a HMAC ellenőrzéshez.

bash

curl -sS -X POST https://api.quick.es/v1/webhooks \
  -H "Authorization: Bearer $QUICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/hooks/quick",
    "events": ["invoice.status_changed"]
  }'

2. Aláírás ellenőrzése

Minden webhook X-QUiCK-Signature fejléccel érkezik, ami a body HMAC-SHA256 aláírása.

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

export function verifySignature(rawBody: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Az ellenőrzés ELŐTT ne írj adatbázisba — egy hamis payload állapotot ronthat el.

3. Idempotens frissítés

A QUiCK ismételheti a webhookot (retry). Használd az esemény id mezőjét kulcsnak, és a payload occurred_at mezőjét összehasonlítva csak akkor frissíts, ha az újabb.

sql

INSERT INTO invoice_status_events (event_id, invoice_id, status, occurred_at)
VALUES ($1, $2, $3, $4)
ON CONFLICT (event_id) DO NOTHING;

UPDATE invoices
SET status = $3, status_updated_at = $4
WHERE id = $2 AND status_updated_at < $4;

4. Reconciliation háló

A webhook nem garantál kézbesítést. Napi egyszer futtass egy full-sync-et: kérdezd le az elmúlt 24 óra updated_at szerint módosult számláit, és javítsd a saját tábládat.

for await (const inv of listInboundInvoices({ updated_since: last24h() })) {
  await upsertInvoiceStatus(inv);
}

5. Riasztás lemaradás esetén

Metrikázd, hány másodperc telik el egy státuszváltás és a saját frissítésed közt. Ha ez 5 percen túl van, riassz — vagy a webhook nem érkezik meg, vagy a fogadód lassú.

Kapcsolódó endpointok

POST/v1/webhooks
GET/v1/invoices

Kapcsolódó fogalmak

webhook status inbound_invoice

Gyakori hibák

HMAC ellenőrzés nélkül fogadja a payloadot

Ez publikus endpoint — bárki küldhet POST-ot. Aláírás nélküli forgalmat 401-gyel dobd vissza.

Retry esetén dupla feldolgozás

Ha nem használsz idempotency kulcsot az esemény id-jára, ugyanaz az állapotváltás többször is átfut.

Nincs full-sync fallback

Webhook-only szinkronban egy elveszett payload csendben lemaradást okoz. Napi reconciliation nélkül nem vagy production-ready.