Mi az a webhook? Hogyan értesítik egymást az appok

A webhook egy automatikus üzenet, amelyet egy szolgáltatás akkor küld az appodnak, amikor valami történik. Ha egy vásárló fizetése sikeres, a Stripe webhookot küld az appodban lévő címre, amely azt mondja: „a fizetés sikeres, íme a részletek”, az appod pedig reagál — megjelöli a rendelést fizetettként, receiptet küld, feloldja a fiókot. Röviden: az API az, amikor az appod kérdez egy másik szolgáltatástól; a webhook az, amikor a másik szolgáltatás hív és közli az appoddal, hogy valami történt.

Miért fontos, ha AI-val építesz

Amint az appod fizetéseket fogad, űrlapbeküldéseket kap egy másik eszköztől, vagy olyan szolgáltatásokhoz kapcsolódik, mint a GitHub, a Shopify vagy egy naptár, találkozni fogsz webhookokkal. Általában ezek a helyes módok arra, hogy megtudd, valami történt — de az AI-val épített appokban itt a leggyakoribb a finom hiba:

• A végpont bármilyen kérést elfogad, így bárki hamis „fizetés sikeres” eseményt küldhet.
• Az app a fizetés utáni átirányítási oldalon ad hozzáférést a webhook helyett, így akik korán bezárják a lapot, nem kapják meg, amit fizettek, az pedig, aki megtalálja a sikeres oldal címét, ingyen jut hozzá.
• Ugyanaz az esemény kétszer érkezik, és a vásárló két rendelést vagy két e-mailt kap.

Ha tudod, hogyan működnek a webhookok, már az elején kérhetsz védelmet.

Egy hétköznapi hasonlat: egy kézbesítési SMS

Kétféleképpen tudhatod meg, megérkezett-e a csomagod. Tíz percenként kimehetsz a bejárathoz, hogy ellenőrizd (ez a polling — az appod ismételten egy API-t hív azzal a kérdéssel: „van új?”). Vagy a futár SMS-ben értesít, amikor kézbesítette (ez a webhook).

Az SMS egyértelműen jobb — ha megbízhatsz benne. Ha bárki küldhetne „kézbesítve” üzenetet, szeretnéd tudni, hogy valóban a futártól jött-e. És ha a telefonod ki volt kapcsolva, amikor az SMS érkezett, szeretnéd, ha a futár később újra próbálná. Ez a két szempont — az ellenőrzés és az újrapróbálkozás — a webhookok nehézségének nagy része.

Hogyan működik a webhook, lépésenként

1. Létrehozol egy végpontot az appod backendjében: egy https://yourapp.com/webhooks/stripe típusú címet, amely POST kéréseket fogad.
2. Regisztrálod a címet a szolgáltatónál, és kiválasztod, mely eseményekre szeretnél értesítést (például „fizetés befejezve” és „előfizetés lemondva”).
3. A szolgáltató ad egy aláírási titkot. Ezt a szervereden titokként tárolod — lásd: környezeti változók és titkok.
4. Történik egy esemény. A szolgáltató HTTP-kérést küld a címedre, JSON-törzzsel, amely leírja az eseményt, plusz egy aláírás-fejléccel.
5. Az appod ellenőrzi az aláírást, rögzíti az esemény azonosítóját, gyorsan válaszol egy sikeres kóddal (200), és csak utána végzi el a munkát.
6. Ha az appod nem válaszol sikeresen, sok szolgáltató később újrapróbálja.

Aláírások

Az aláírás bizonyítja, hogy a kérés a szolgáltatótól érkezett, és nem változtatták meg. A Stripe például a kérés törzséről és egy időbélyegről HMAC-et (egy kulccsal készült ujjlenyomatot, SHA-256 algoritmussal) számol az aláírási titok felhasználásával, és a Stripe-Signature fejlécben küldi el. Az appod ugyanezt a számítást elvégzi a saját titkának másolatával; ha az eredmény egyezik, a kérés valódi. Mivel az időbélyeg is alá van írva, el tudod utasítani a régi kéréseket, amelyeket valaki rögzített és később visszajátszik — a Stripe könyvtárai alapértelmezésben öt perces tűréshatárt használnak, a Stripe dokumentációja szerint 2026 szeptemberében.

Egy gyakorlati részlet: az aláírást a nyers kérés törzsén számolják. Ha a keretrendszered a JSON-t ellenőrzés előtt feldolgozza és újraformázza, az ellenőrzés meghiúsul. Ez nagyon gyakori hiba.

Újrapróbálkozások, duplikációk és sorrend

A szolgáltatók eltérően működnek, ezért mindig nézd meg a dokumentációjukat. 2026 szeptemberében:

A Stripe dokumentációja azt is kimondja, hogy az események érkezési sorrendje nem garantált az előfordulásuk sorrendjéhez képest, és hogy ugyanaz az esemény ritkán többször is megérkezhet, ezért az esemény-azonosítók nyilvántartását javasolja.

Az általános tanulság bármely szolgáltatóra igaz: az események késve, többször és rossz sorrendben érkezhetnek. A kezelődnek idempotensnek kell lennie — ugyanannak az eseménynek kétszeri feldolgozása ugyanazt az eredményt adja, mint az egyszeri.

Kidolgozott példa: egy fizetős kurzus feloldása

Online kurzust árulsz. Egy diák rákattint a Vásárlás gombra, a Stripe hosted fizetési oldalán fizet, majd visszaküldik a weboldaladra.

A törékeny módszer: a „köszönjük” oldal oldja fel a kurzust. Ha a diák az átirányítás közben bezárja a böngészőt, fizetett, de nincs hozzáférése. Ha valaki kitalálja a köszönő oldal címét, fizetés nélkül kap hozzáférést.

A webhookos módszer:

1. Amikor a Stripe megerősíti a fizetést, elküldi a checkout.session.completed eseményt a /webhooks/stripe címre.
2. A backendod ellenőrzi az aláírást az aláírási titokkal. Ha nem stimmel, 400-zal válaszol, és nem csinál semmit.
3. Megnézi, hogy az esemény azonosítója már feldolgozásra került-e. Ha igen, 200-zal válaszol és megáll.
4. Elmenti az esemény azonosítóját, 200-zal válaszol, majd hozzáférést ad a diáknak és üdvözlő e-mailt küld.
5. A köszönő oldal csak annyit mond: „A fizetés megérkezett — a kurzus hamarosan megjelenik”, és ellenőrzi a diák hozzáférési állapotát.

Később, ha egy előfizetést lemondanak vagy egy kártya nem fizet, más webhook-események jelzik az appodnak, hogy el kell távolítani vagy fel kell függeszteni a hozzáférést. Így maradnak szinkronban az előfizetéses termékek a számlázással — lásd: mi az a SaaS és hogyan adj fizetést az appodhoz.

Kulcsfogalmak

• Végpont (endpoint): az appodban lévő cím, amely a webhookokat fogadja.
• Esemény / payload: mi történt, és az ezt leíró adat (általában JSON).
• Aláírási titok: az aláírások ellenőrzéséhez használt, megosztott titok.
• Idempotens: biztonságosan futtatható többször is, azonos eredménnyel.
• Polling: egy API ismételt kérdezése a változásokról, ahelyett hogy egy webhookra várnál.
• Alagút (tunnel): eszköz, amely ideiglenes nyilvános címet ad a laptopodnak, hogy a webhookok fejlesztés közben elérjék.

Gyakori hibák és tévhitek

• Az aláírások nem ellenőrzése. A végpont címe nem titok. Az ellenőrzés teszi megbízhatóvá a kérést.
• Lassú munka a válasz előtt. E-mailek küldése vagy PDF generálása a válasz előtt időtúllépéshez vezethet, ami újrapróbálkozást vált ki, ami duplikációkat okoz.
• Az egyszeri, sorrendhelyes kézbesítés feltételezése. Rögzítsd az esemény-azonosítókat, és ne támaszkodj az érkezési sorrendre.
• Előnézeti cím használata. A webhookokhoz stabil, nyilvános cím kell. A privát előnézetek és a localhost nem érhetők el az internetről; használd a publikált címet (vagy alagutat teszteléskor).
• Teszt- és éles titkok keverése. A szolgáltatók gyakran eltérő aláírási titkokat adnak a teszt- és az éles módhoz. Tárold mindkettőt, és mindig a megfelelőt használd.
• Az adatnak vakon bízni fontos döntéseknél. Kockázatos műveleteknél ésszerű az esemény fogadása után a szolgáltató API-jától lekérni a legfrissebb állapotot.

Mit kérj az AI-építődtől

Adj egy POST /webhooks/stripe végpontot a szerveren. Ellenőrizd a Stripe-aláírást a nyers kérés törzsével és a STRIPE_WEBHOOK_SECRET titokkal. Az érvénytelen aláírásokat 400-zal utasítsd el. Tárold az egyes esemény-azonosítókat, és hagyd ki a már feldolgozottakat. 200-zal válaszolj gyorsan, majd kezeld a checkout.session.completed eseményt: jelöld a rendelést fizetettként és küldd el a nyugtát. Naplózd az esemény típusát. Ne adj hozzáférést a fizetés sikeres oldaláról.

Ezután teszteld: küldj teszt-eseményt a szolgáltató felületéről, küldd el ugyanazt még egyszer, és küldj egy kérést rossz aláírással. Csak az első változtasson bármin.

Webhookok a Mythexben

A Mythexnek nincs külön webhook-szolgáltatása; az ügynöktől kéred, hogy adjon hozzá webhook-végpontot az appod saját backendjéhez, a szolgáltatót pedig a publikált címedre irányítod, mert a webhookoknak nyilvános címre van szükségük. Az aláírási titok a projekt titkai közé kerül, és ha élő appon megváltoztatod, újra kell publikálnod. A dokumentáció webhookok kezelése receptje tartalmaz kiinduló promptot, és a bolt-sablonok jó kiindulópontot adnak a fizetést fogadó appokhoz.

Kérdések