Webhookok és külső integrációk

19.1Bejövő webhook: a helyes szerkezet

A leggyakoribb hiba, hogy a webhook-végpont mindent egyben csinál: ellenőriz, feldolgoz, DB-t ír, emailt küld — és a küldő fél közben vár. Ha bármelyik lépés lassú vagy hibázik, a partner újraküldi az eseményt, és kezdődik a duplikációs káosz. A helyes szerkezet kétfázisú:

Aláírás-ellenőrzés Workersen — a nyers body csapdája

Ez a rész az, ahol Node-ból érkezve el lehet csúszni. Az aláírás a nyers, bájtszintű törzs felett készül — ha a keretrendszered már JSON-ná alakította és újra sorosítod, az ellenőrzés hibázni fog (más lesz a szóköz, a kulcssorrend). Workersön szerencsére egyszerű a helyzet: a request.text() pontosan azt adja, ami érkezett — csak arra kell figyelni, hogy előbb a szöveget vedd ki, és abból parse-olj, ne fordítva.

export default defineEventHandler(async (event) => {
  const { env, context } = event.context.cloudflare;

  // 1) NYERS törzs — ebből lesz az aláírás-ellenőrzés alapja
  const raw = await readRawBody(event, "utf8");
  const sig = getHeader(event, "stripe-signature");

  // 2) HMAC ellenőrzés Web Cryptóval (nincs natív modul, 2. modul)
  if (!(await verifyStripeSignature(raw, sig, env.STRIPE_WEBHOOK_SECRET))) {
    throw createError({ statusCode: 400, message: "invalid signature" });
  }

  const evt = JSON.parse(raw);          // csak az ellenőrzés UTÁN parse-olunk

  // 3) dedup: ugyanaz az esemény kétszer is megérkezhet
  const inserted = await env.DB.prepare(
    "INSERT OR IGNORE INTO webhook_events (id, provider, received_at) VALUES (?, 'stripe', ?)"
  ).bind(evt.id, new Date().toISOString()).run();

  if (inserted.meta.changes === 0) return { ok: true, duplicate: true };

  // 4) sorba tesszük — a valódi munka a consumerben (7. modul)
  await env.JOBS.send({ type: "stripe-event", eventId: evt.id, payload: evt });

  return { ok: true };      // gyors 200 → a partner nem küldi újra
});

export async function verifyStripeSignature(raw, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const t = parts.t, v1 = parts.v1;

  // replay-védelem: a túl régi aláírást ne fogadjuk el
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const key = await crypto.subtle.importKey(
    "raw", new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);

  const mac = await crypto.subtle.sign(
    "HMAC", key, new TextEncoder().encode(`${t}.${raw}`));

  return timingSafeEqual(toHex(mac), v1);   // időállandó összehasonlítás!
}

Miért ne a waitUntil-t használd a feldolgozásra?

Kísértő megoldás: gyors 200, a munka pedig ctx.waitUntil()-ben. Ez kis dolgokra (log, metrika) rendben van, de webhookra nem: ha a háttérfeldolgozás hibázik, nincs retry — a partner már 200-at kapott, nem küldi újra, az esemény pedig elveszett. A Queue épp ezt a garanciát adja: retry, késleltetés, DLQ (7. modul).

19.2Idempotencia — a hálózat mindig kétszer csenget

Két oka is van, hogy ugyanaz az esemény többször feldolgozásra kerüljön: a partner újraküldi (mert nem kapott időben választ), és a Queue is legalább-egyszeri kézbesítésű (7. modul). Ezért a feldolgozásnak idempotensnek kell lennie — háromszintű védelem:

async queue(batch, env) {
  for (const msg of batch.messages) {
    try {
      const { eventId, payload } = msg.body;

      // 2. szint: az állapot dönt, nem az esemény érkezése
      const already = await env.DB.prepare(
        "SELECT processed_at FROM webhook_events WHERE id = ?"
      ).bind(eventId).first();
      if (already?.processed_at) { msg.ack(); continue; }

      await handleStripeEvent(env, payload);

      await env.DB.prepare(
        "UPDATE webhook_events SET processed_at = ? WHERE id = ?"
      ).bind(new Date().toISOString(), eventId).run();

      msg.ack();
    } catch (err) {
      msg.retry({ delaySeconds: 60 });     // hibánál újra, DLQ-ig (7. modul)
    }
  }
}

19.3Kimenő webhookok: te vagy a küldő

Ha az ügyfeleid webhookokat kapnak tőled (ez B2B SaaS-nál elvárás), a felelősség megfordul. Amit a te oldaladról meg kell oldani:

async function deliver(env, endpoint, event) {
  const body = JSON.stringify(event);
  const ts = Math.floor(Date.now() / 1000);
  const sig = await hmacHex(endpoint.secret, `${ts}.${body}`);

  const res = await fetch(endpoint.url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-MyApp-Signature": `t=${ts},v1=${sig}`,
      "X-MyApp-Event-Id": event.id,
      "X-MyApp-Delivery": crypto.randomUUID(),
    },
    body,
    signal: AbortSignal.timeout(10_000),   // ne lógjon örökké
  });

  if (!res.ok) throw new Error(`delivery failed: ${res.status}`);
}

19.4Kimenő API-hívások: partner-integrációk

Amikor te hívsz külső API-t (fizetés, számlázó, CRM), a Workers-környezet néhány szabálya érvényes:

• Ne a globális scope-ban példányosíts klienst (2. és 4. modul) — a handleren belül hozd létre.
• Egyidejűség: maximum 6 nyitott kimenő kapcsolat kérésenként (2. modul). Nagy Promise.all-nál batchelj.
• Subrequest-limit: alapból 10 000/kérés a fizetős csomagon, konfigurálható (2. modul) — hosszú Workflow-knál emeld.
• Timeout mindig legyen (AbortSignal.timeout): egy lassú partner ne tartsa fogva a kérésedet.
• Retry csak idempotens műveletre, exponenciális visszalépéssel; a partner Retry-After fejlécét vedd figyelembe.
• Rate limit a partner felé: ha a partner API-ja korlátozott, a kimenő hívásokat is soroljad (Queue) — így nem te leszel, aki 429-et kap élesben.
• Cache a lassan változó válaszokra: fetch() + cf.cacheTtl vagy KV (18. modul) — árfolyam, ország-lista, adószám-ellenőrzés.

19.5Tesztelés és fejlesztés

• Lokális webhook-fogadás: wrangler dev --tunnel — a lokális dev szervered kap publikus URL-t, amit beírhatsz a Stripe/GitHub webhook-beállításába (11. modul). Nincs szükség ngrokra.
• Aláírás-teszt: írj unit tesztet (11. modul), ami érvényes és érvénytelen aláírással is meghívja a handlert — ez az egyik legfontosabb biztonsági teszted.
• Idempotencia-teszt: ugyanazt az eseményt kétszer dolgozd fel a tesztben, és ellenőrizd, hogy csak egy hatása van.
• DLQ-figyelés: a 7. modul mintája — a DLQ-consumer riasszon, ne csak gyűjtsön.

19.6Ellenőrizd magad