A webhookot HTTPS-en keresztül fogadja, ellenőrizze az aláírást az eredeti törzsön és az üzenet idejét, validálja a sémát, és az eseményt egyedi azonosítóval mentse. Válaszoljon gyorsan, és dolgozza fel idempotens módon egy sorban. Számoljon a duplikációval és a megváltozott sorrenddel, monitorozza a hibákat, és rendszeresen egyeztesse a kritikus adatokat.
A webhook olyan üzenet, amellyel az egyik rendszer értesíti a másikat egy eseményről, például beérkezett fizetésről, egy küldemény változásáról vagy új kapcsolatról. Az állapot rendszeres lekérdezéséhez képest gyorsan és kevesebb kéréssel képes reagálni. Az interneten keresztüli kézbesítés azonban nem tökéletesen rendezett sor: az üzenet érkezhet többször, késve, párhuzamosan vagy egyáltalán nem. A fogadónak számolnia kell ezekkel a tulajdonságokkal.
Egy biztonságos endpoint sem bízhat meg tetszőleges JSON-ban csak azért, mert helyesnek tűnik. Ellenőrzi az esemény eredetét, integritását, idejét, formátumát és jogosultságát. A feldolgozás elválasztja a gyors fogadást a lassú üzleti munkától, és fenntartja a megfigyelhetőséget. Az alábbi megoldás WordPresshez, WooCommerce-hez és önálló alkalmazáshoz is használható.
Határozza meg az esemény szerződését és életciklusát
Dokumentálja az eseménytípusokat, a verziót, az egyedi azonosítót, a keletkezés idejét, az objektum identitását és az adatsémát. Különböztesse meg, hogy a payload (az üzenet törzse) a teljes aktuális objektumot tartalmazza-e, vagy csak egy értesítést, amely után meg kell hívni az API-t. Teljes objektum esetén egy késve érkező régebbi esemény felülírhatja az újabb állapotot; az utólagos API-hívásnál viszont kezelni kell a korlátokat és az elérhetetlenséget. A választás a szolgáltatótól és az elvárt konzisztenciától függ.
Az események állapota lehet fogadott, ellenőrzött, várakozó, feldolgozott vagy hibás. Az eredeti törzset az érzékenységnek megfelelően tárolja, és korlátozza a megőrzési időt. Az egyedi azonosító véd a duplikáció ellen, a korrelációs azonosító pedig összeköti a későbbi lépéseket. Határozza meg az üzleti objektum végső és átmeneti állapotait, hogy egy késve érkező „fizetés függőben” üzenet ne állítsa vissza a már kifizetett rendelést.
Ellenőrizze az aláírást, és akadályozza meg az ismételt visszaélést
Az aláírást pontosan a szolgáltató dokumentációja szerint ellenőrizze, általában a kérés módosítatlan törzse és az időbélyeg alapján. Ha a keretrendszer előbb újraformázza a törzset, az eredő aláírás eltérhet. Az összehasonlítást biztonságos módon végezze, és az érvénytelen üzenetet utasítsa el az üzleti feldolgozás előtt. A titkos kulcsot biztonságos konfigurációban tárolja, használjon külön értékeket az egyes környezetekhez, és készítse elő a kulcsrotációt.
Az időablak és az azonosítók nyilvántartása csökkenti egy elfogott érvényes üzenet ismételt lejátszásának kockázatát. Az IP-allowlist kiegészítő réteg lehet, ha a szolgáltató stabil tartományokat tesz közzé, de nem az eredet egyetlen bizonyítéka. Az endpointot korlátozza a törzs méretével, a támogatott metódusokkal és sebességkorláttal. A hibaválaszok nem tesznek közzé stack trace-t vagy titkokat. Saját küldő esetén ugyanígy védje a fogadót és az aláírókulcsot is.
- HTTPS és aláírás az eredeti törzs felett
- Időbeli tolerancia és egyedi azonosító
- Elkülönített titkos adatok és rotációs terv
- Méretkorlát, metódusok és gyakoriság
Válaszoljon gyorsan, és dolgozza fel várakozási sorban
A végpont ellenőrizze és tartósan mentse az eseményt, majd gyorsan adjon vissza sikeres választ. Ha egyetlen kérés során dokumentumot generál, három API-t hív és e-mailt küld, a szolgáltató időtúllépést állapíthat meg, és megismételheti az eseményt. A sor elválasztja a fogadást a feldolgozástól, lehetővé teszi a párhuzamosság korlátozását, és megőrzi az üzenetet egy függőség átmeneti kiesése alatt. A visszaigazolást azonban csak a biztonságos mentés után küldje, ne előtte.
A worker idempotens műveletet használ, és ellenőrzi az objektum aktuális állapotát. Az átmeneti hibát növekvő időközzel újrapróbálja, a séma vagy a jogosultság tartós hibáját pedig karanténba helyezi. A próbálkozások számának és az esemény korának is van korlátja. Az adminisztráció vagy a dashboard lehetővé teszi, hogy a javított üzenetet biztonságosan újra lehessen futtatni az adatbázis kézi módosítása nélkül. Szigorú sorrend esetén az eseményeket objektumonként szekvenciálisan dolgozza fel, vagy használja az állapot verzióját.
Küldéskor vegye figyelembe a címzettet
Saját webhookot egyértelmű dokumentációval, verzióval és aláírással küldjön. A fogadó végpontot regisztráláskor validálja, az érzékeny címváltozást pedig erősíttesse meg. Állítson be időkorlátot, korlátozott számú próbálkozást és véletlenszerű szórással kiegészített exponenciális várakozást. A sikert a megállapodott állapotkód-tartomány alapján határozza meg. Tartós kliensoldali hibát ne ismételjen a végtelenségig, de az okot tegye elérhetővé az integráció tulajdonosa számára.
Minden előfizetőnek saját titka van, és a többiek befolyásolása nélkül szüneteltethető. Naplózza az esemény azonosítóját, a célt, a kísérletet, az időt és a biztonságos eredményt. Minimalizálja a payloadot, és az érzékeny adatokat inkább egy hitelesített, utólagos API-hívással tegye elérhetővé, ha a modell ezt lehetővé teszi. Séma módosításakor adjon hozzá verziót és átmeneti időszakot; a csendes inkompatibilitás veszélyesebb, mint egy kifejezetten elutasított új verzió.
- Külön titok minden címzett számára
- Időtúllépés és szabályozott újrapróbálkozás
- Verziózott payload minimális adatokkal
- Szüneteltetés és újbóli kézbesítés lehetősége
Tesztelje és egyeztesse a kritikus adatokat
A tesztek lefedik az érvényes és érvénytelen aláírást, a régi időbélyeget, a duplikációt, az egyidejű feldolgozást, a megváltozott sorrendet, a sérült JSON-t, az időtúllépést és a függőségek hibáját. Biztosítson a fejlesztőknek biztonságos módot a tesztesemény megismétlésére, valamint éles személyes adatokat nem tartalmazó minta-payloadokat. Helyi tunnel használatakor ügyeljen a hozzáférésre, és a teszt után kapcsolja ki. A terheléses teszt a sort és a végpont védelmét is ellenőrzi.
A monitoring a fogadás, az ellenőrzés és a feldolgozás arányát, az újrapróbálkozások számát, a sor korát és a karantént követi. A kritikus adatokat rendszeresen egyeztesse API-n vagy exporton keresztül, mert a webhook nem feltétlenül az egyetlen hiteles forrás. Ha eltérés mutatkozik, a folyamat kijavítja, vagy ember elé terjeszti. A runbook elmagyarázza, hol található az esemény, hogyan ellenőrizhető az állapot a szolgáltatónál, és mikor biztonságos az újrapróbálkozás.
Gyakori kérdések
Mi a különbség az API és a webhook között?
Az API-t általában akkor hívják, amikor a kliens adatot vagy műveletet kér; a webhookot a szolgáltató indítja egy esemény bekövetkeztekor. Gyakran kombinálják őket: a webhook jelzi a változást, a fogadó fél pedig az API-n keresztül lekéri az ellenőrzött aktuális állapotot.
Miért érkezett meg kétszer a webhook?
A szolgáltató időtúllépés vagy hiányzó visszaigazolás után megismételheti a kézbesítést, és a hálózat nem tudja garantálni, hogy pontosan egy kísérlet történik. A fogadó félnek eseményazonosítót és idempotens feldolgozást kell használnia, nem pedig egyetlen kézbesítést feltételeznie.
Mindig sikert kell visszaadnia az endpointnak?
Nem. Az érvénytelen aláírást vagy sémát megfelelő státusszal el kell utasítani. Érvényes esemény esetén csak a biztonságos mentés után küldjön visszaigazolást. A konkrét válaszra és az újrapróbálkozási szabályokra a szolgáltató dokumentációja és az Ön szerződése az irányadó.
Források és további olvasnivaló
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
