Webhook: szolgáltatás hívja a fogyasztót

Célok

A lecke végére el tudod magyarázni a webhook működését, meg tudod különböztetni a pollingtól és a WebSockettől, és fel tudod sorolni a fogadó oldal teendőit.

Miért kell?

Ha egy külső szolgáltatás eseményeiről értesülni kell, a polling (9.1) késleltet és terhel, a tartós kapcsolat (10. fejezet) pedig szervezési terhet jelent. A webhook megfordítja az irányt: az esemény bekövetkeztekor a forrás hívja a fogyasztó előre megadott címét.

Mi a webhook?

A webhook olyan HTTP-hívás, amelyet a szolgáltatás (az esemény forrása) egy esemény bekövetkezésekor a fogyasztó regisztrált végpontjára küld. A kezdeményező a szolgáltató, a fogyasztó fogadó végpontot üzemeltet. Nem tartós kétirányú csatorna és nem a böngésző értesítése: szolgáltatások közötti, eseményhez kötött HTTP-kérés.

sequenceDiagram
  participant F as Forrásszolgáltatás
  participant V as Fogadó végpont
  Note over F: Esemény történik
  F->>V: POST (esemény + aláírás)
  V-->>F: 2xx (átvétel)
  Note over V: Feldolgozás később

A fogadó oldal teendői

A GitHub webhook-útmutatója jól mutatja a gyakorlati követelményeket:

• Gyorsan válaszolni egy 2xx-szel (a GitHub szerint 10 másodpercen belül, különben a kézbesítést sikertelennek számítja), és a tényleges feldolgozást háttérsorban végezni. A sikeres válasz tehát átvételt jelez, nem teljes üzleti feldolgozást.
• Ellenőrizni a feladót. A GitHub HMAC-aláírást (hash-based message authentication code, kulcsos lenyomat) számol a tartalomból és a közös titokból SHA-256-tal, és az X-Hub-Signature-256 fejlécben küldi; a fogadó a nyers, módosítatlan törzsből maga is kiszámolja, és állandó idejű összehasonlító függvénnyel veti össze. A tartalom újraszerializálása megváltoztathatja a bájtokat; a közbenső komponensek is elronthatják az ellenőrzést.
• Duplikációt kezelni. A GitHub kézbesítési azonosítót (X-GitHub-Delivery) küld, amellyel az ismétlés felismerhető; az újrakézbesítés megőrzi az eredeti értéket. A fogadónak ezért idempotensnek kell lennie (6.5, 8.2).
• A kihagyott eseményeket újra lehet küldeni: a GitHub útmutatója szerint az újrakézbesítés a fogadó dolga és lehetősége, nem automatikus.
• HTTPS-t használni, és a titkot biztonságosan tárolni.

Időbélyeg és korlátozott elfogadási időablak védhet a visszajátszás ellen, de az ablakot a szolgáltató ismétlési rendjéhez kell igazítani.

Jellemzők

Szempont	Webhook
Irány	Egyirányú: forrás → fogadó
Kezdeményező	A forrásszolgáltatás
Kapcsolat tartóssága	Eseményenként egy kérés
Késleltetés	Az esemény után gyors, de a fogadó elérhetőségétől függ
Terhelés	Csak eseményenként; a fogadónak publikus végpont kell
Hibatűrés	Ismétlés, duplikáció, kihagyott kézbesítés; a fogadónak idempotensnek kell lennie
Mikor jó?	Szolgáltatások közötti ritka vagy közepes gyakoriságú értesítés
Mikor nem?	Böngészős kliens frissítése; sűrű, kétirányú üzenetváltás; ha a fogadó nem érhető el kívülről

Webhook és társai

• Polling: a fogadó kérdez; webhooknál a forrás küld, így nincs üres kérdezés.
• WebSocket / SSE: tartós csatorna egy klienssel; a webhook szerver–szerver és eseményenként új kérés.
• Üzenetsor: a fogadónak nem kell elérhetőnek lennie a küldéskor; a webhook elérhető végpontot igényel, és a fogadó elérhetősége a küldő ismétlési rendjétől függ.

Gyakori tévhitek

Állítás	Pontosítás
„A webhook a böngésző értesítése.”	Szolgáltatás hívja a másik szolgáltatás végpontját.
„A webhook WebSocket szerverek között.”	Eseményenként új HTTP-kérés, nem tartós csatorna.
„Aláírás nélkül is megbízható.”	Az aláírás igazolja a feladót.
„A 2xx válasz azt jelenti, hogy feldolgoztuk.”	Átvételt jelez, a feldolgozás később történhet.

Röviden

• A webhook esemény hatására küldött HTTP-hívás a fogadó végpontjára; a kezdeményező a forrás.
• A fogadó gyorsan válaszol, ellenőrzi az aláírást, deduplikál, és később dolgozza fel.
• Az újrakézbesítés nem automatikus; idempotencia kell.
• Szerver–szerver értesítésre jó, nem böngészős frissítésre.

Ellenőrző kérdések

1. Miben különbözik a webhook a pollingtól és a WebSockettől?
2. Miért kell a nyers törzsből ellenőrizni az aláírást?
3. Miért idempotens kell legyen a webhook fogadója?

Források

• Validating webhook deliveries (GitHub Docs) — HMAC, nyers törzs, állandó idejű összehasonlítás.
• Best practices for using webhooks (GitHub Docs) — gyors válasz, háttérfeldolgozás, deduplikálás.