A webhookok integrációja során a beérkező kérések pontos szerkezetének megértése elengedhetetlen a hibamentes feldolgozáshoz. A Webhook-kérés vizsgáló eszköz lehetővé teszi a rögzített webhook-kérések módszerének, fejléceinek és törzsének részletes elemzését, valamint egy helyi tesztelésre használható cURL parancs előállítását. Az eszköz segítségével az API-fejlesztők, integrációs mérnökök, ügyfélszolgálati képviselők és az automatizálások karbantartói gyorsan átláthatják a kérések felépítését, ellenőrizhetik a formázást, és azonosíthatják a biztonsági hitelesítéshez használt fejléceket.
A webhook-kérések szerkezete és a fejlécek szerepe
A webhookok lényegében fordított API-hívások, ahol egy külső rendszer HTTP-kérést küld az Ön szerverére egy esemény bekövetkeztekor. A kérés pontos elemzéséhez három fő összetevőt kell vizsgálni: a HTTP-módszert, a fejléceket és a kérés törzsét.
A HTTP-fejlécek kulcsfontosságú szerepet játszanak a webhook-kommunikációban. Ezek hordozzák a metaadatokat, például a tartalom típusát, a küldő azonosítóját, valamint a biztonsági ellenőrzéshez szükséges kriptográfiai aláírásokat és időbélyegeket. A Webhook-kérés vizsgáló használatával a rögzített fejlécek soronként, "Név: érték" formátumban elemezhetők. Az eszköz legfeljebb 200 nem üres fejlécsort képes feldolgozni, a fejlécek maximális hossza pedig 100 000 karakter lehet.
Támogatott törzsformátumok és a nyers tartalom fontossága
A webhookok leggyakrabban JSON vagy URL-kódolt űrlapadatként továbbítják az információkat. A feldolgozás során kritikus fontosságú a nyers, szerveroldali elemzés előtti kéréstörzs megőrzése. A Webhook-kérés vizsgáló a következő szabályok szerint kezeli a beillesztett törzset (amely legfeljebb 1 000 000 karakter hosszú lehet):
- JSON formátum: Ha a törzs JSON-ként van kódolva, az eszköz a
JSON.parsefüggvény segítségével elemzi és újrarendezi azt. Emiatt az eredeti szóközök, soremelések és a mezők eredeti sorrendje módosul a formázott kimenetben. - URL-kódolt űrlapadatok: Az eszköz automatikusan felismeri és olvasható formátumba rendezi az URL-kódolt kulcs-érték párokat.
- Egyéb formátumok: Minden más típusú törzs (például XML vagy sima szöveg) nyers, formázatlan szövegként jelenik meg.
Ha a kérés törzse üres, a kimenetben a "(üres törzs)" jelzés jelenik meg.
Webhook-aláírások és időbélyegek azonosítása
A biztonságos webhook-feldolgozás alapja a küldő fél hitelességének ellenőrzése. A küldő rendszerek gyakran egy speciális fejlécben helyezik el a kérés tartalmából generált kriptográfiai aláírást (például HMAC-et) és a küldés időbélyegét.
A Webhook-kérés vizsgáló képes automatikusan azonosítani a gyakori aláírási és időbélyeg-fejléceket a név mintázata alapján (például signature, hmac, digest vagy ismert időbélyeg-nevek). Fontos azonban tisztázni a különbséget a vizsgáló eszköz általi azonosítás és a tényleges hitelesítés között:
- Mit tesz az eszköz? Megkeresi és kilistázza ezeket a fejléceket a könnyebb áttekinthetőség érdekében.
- Mit nem tesz meg? Nem számol HMAC-et, nem hajt végre algoritmus-ellenőrzést, nem veti össze a kérés eredeti bájtjait a titkos kulccsal, nem vizsgálja meg a visszajátszási időablakot (replay window), és nem végez szolgáltató-specifikus ellenőrzést.
Az aláírás mező megléte nem bizonyítja a kérés hitelességét — a valódi ellenőrzéshez a küldő aláírási szabályaira, titkos kulcsára és az eredeti kérés bájtjaira van szükség.
Helyi tesztelés cURL segítségével
A webhookok fejlesztése során a helyi hibakeresés egyik leghatékonyabb módja a kérések reprodukálása. Az eszköz a beillesztett adatok alapján automatikusan generál egy shell-idézőjelekkel ellátott cURL parancsot.
Ez a generált parancs fixen a http://localhost:3000/webhooks helyi végpontot célozza meg. Segítségével a rögzített kérést pontosan ugyanazokkal a fejlécekkel és törzzsel küldheti el újra a saját fejlesztői környezetében futó alkalmazásának, anélkül, hogy meg kellene várnia a külső szolgáltató tényleges eseményeit.
Hibakezelés és korlátok
A beillesztett adatok elemzése során az eszköz az alábbi hibaüzenetekkel jelezheti a formázási vagy méretbeli problémákat:
| Hibaüzenet | Kiváltó ok |
|---|---|
| "Először illesszen be legalább egy fejlécet vagy egy kérés törzsét." | Az elemzés indításakor mindkét beviteli mező üres volt. |
| "A fejlécek túl hosszúak ehhez az eszközhöz. Távolítsa el a nem kapcsolódó vagy ismétlődő értékeket." | A fejlécek együttes hossza meghaladta a 100 000 karaktert. |
| "A test túl hosszú ehhez az eszközhöz. Tartsa 1 000 000 karakter alatt." | A beillesztett törzs mérete átlépte az 1 000 000 karakteres korlátot. |
| "Túl sok fejlécsor van. Tartsa a kérést legfeljebb 200 fejlécben." | A megadott fejlécek száma meghaladja a 200 sort. |
"‹line›: A fejléc sora érvénytelen. Használja a nevet: érték." |
Egy adott sor nem felel meg a kötelező "Név: érték" formátumnak. |
| "A törzs JSON-nak tűnik, de nem lehetett elemezni." | A tartalom JSON-szerű, de szintaktikai hibát tartalmaz, így a JSON.parse nem tudta feldolgozni. |
| "Az űrlaptörzs hiányos százalékos kilépést tartalmaz." | Az URL-kódolt törzsben hibás vagy félbehagyott százalékos kódolás (percent-encoding) található. |
Adatkezelés és adatvédelem
A webhook-kérések gyakran tartalmazhatnak érzékeny adatokat, ügyfélinformációkat vagy belső rendszerazonosítókat. A Webhook-kérés vizsgáló használata során a beillesztett kérelme a böngészőben marad. A BroBroGo nem tölti fel és nem menti el a megadott adatokat, a feldolgozás teljes egészében kliensoldalon történik.
Gyakran Ismételt Kérdések (FAQ)
Fogadhat ez az oldal élő webhook visszahívást?
Nem. Illesszen be egy rögzített kérést ellenőrzés céljából. Az oldal nem hoz létre nyilvános végpontot, nem fogad visszahívásokat, és nem küldi el a generált tesztkérést.
Milyen webhook törzsformátumokat vizsgálhatok meg?
JSON és URL-kódolású űrlaptörzsek észlelése és formázása támogatott. Más törzsek sima szövegként maradnak, így az eszköz nem találja ki az XML, többrészes vagy bináris tartalmat.
Az aláírásmező megtalálása bizonyítja a kérés hitelességét?
Nem. Az eszköz csak az aláírás és a kapcsolódó időbélyeg fejléceket jeleníti meg. A valódi ellenőrzéshez a küldő pontos aláírási szabályaira, titkos vagy nyilvános kulcsára és az eredeti kérés bájtjaira van szükség.