> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhookok áttekintése > Ismerje meg, hogyan kézbesíti a ThunderPhone a valós idejű eseményeket, hogyan ellenőrizheti az aláírásokat, valamint hogyan viszonyul egymáshoz a régi és a végpont-alapú kézbesítési modell. A ThunderPhone HTTP `POST` kéréseket küld az Ön szerverének, amikor egy hívás során esemény történik — bejövő hívás indul, hívás ér véget, értékelési futás fejeződik be, riasztás aktiválódik stb. **Két kézbesítési modell** érhető el: Több URL, végpontonkénti titkos kulcsok, végpontonkénti eseményszűrők és automatikus újrapróbálkozások. Kezelés: `GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints`. Szervezetenként egy URL. A hívás-életciklus eseményeit tartalmazza, beleértve a **blokkoló** konfigurációs adatcseréket is. Kezelés: `GET/PUT /v1/webhook`. Az [eseménykatalógus](/hu/webhooks/events) mind a tíz eseménytípusa webhook-végpontokon keresztül kerül kézbesítésre. A hat hívás-életciklus esemény (`telephony.incoming`, `telephony.complete`, `telephony.tool`, `web.incoming`, `web.complete`, `web.tool`) **szintén** elküldésre kerül az örökölt, egy URL-es webhooknak — ha örökölt URL-je és egyező végpontja is van, az eseményt **mindkét** útvonalon megkapja. A blokkoló működés (a [`telephony.incoming` / `web.incoming` konfigurációs adatcsere](/hu/webhooks/call-incoming) és a webhook módú [eszközdiszpécselés](/hu/tools/overview)) kizárólag az örökölt útvonalon érhető el; minden végpontkézbesítés azonnali visszajelzés nélküli értesítés. ## Payload formátuma A végpontkézbesítések egy `data`, `event_id` és `type` mezőket tartalmazó JSON-objektumok: ```json theme={null} { "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }, "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11", "type": "telephony.incoming" } ``` Az `event_id` minden kibocsátott eseményhez egyedi. Azonos az újrapróbálkozások során **és** minden olyan végponton, amely megkapja az eseményt — ezt használja deduplikálásra. Az örökölt, egy URL-es webhook ugyanazt a `type` és `data` mezőt küldi, de `event_id` **nélkül**: ```json theme={null} { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` Az átvitel során minden törzs kanonikus formában szerializálódik — a kulcsok betűrendbe vannak rendezve, nincs üres karakter, a kódolás pedig UTF-8. A dokumentációban szereplő formázott példák kizárólag az olvashatóságot szolgálják. Az eseménytípusok és payloadmezők teljes listájáért tekintse meg az [Eseménykatalógust](/hu/webhooks/events). ## Aláírás ellenőrzése Minden kérés a **nyers kéréstörzs** feletti HMAC-SHA256-aláírást tartalmazza az `X-ThunderPhone-Signature` fejlécben. Az aláírókulcs a végpont `secret` értéke (vagy örökölt kézbesítések esetén a szervezeti szintű webhook `secret` értéke). ### Lépések 1. Olvassa be a nyers kéréstörzset **minden feldolgozás előtt**. 2. Számítsa ki: `hmac_sha256(secret, body).hexdigest()`. 3. Hasonlítsa össze konstans időben az `X-ThunderPhone-Signature` fejléc értékével. Pontosan azokat a bájtokat írjuk alá, amelyeket továbbítunk, és ezek a bájtok a kanonikus JSON-szerializálást alkotják (rendezett kulcsok, tömör elválasztók). Ezért a nyers törzs ellenőrzése mindig működik — és ha a keretrendszere csak feldolgozott JSON-t ad át, annak rendezett kulcsokkal és tömör elválasztókkal történő újraszerializálása azonos bájtokat eredményez. Mindkét eljárást ismerteti az [ellenőrzési útmutató](/hu/guides/verify-webhook-signatures). ```python Python theme={null} import hmac import hashlib def verify_signature(body: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode("utf-8"), body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, signature or "") # Example Flask handler from flask import Flask, request, abort app = Flask(__name__) @app.post("/thunderphone-webhook") def handle(): body = request.get_data() sig = request.headers.get("X-ThunderPhone-Signature", "") if not verify_signature(body, sig, WEBHOOK_SECRET): abort(401) event = request.get_json() # dispatch on event["type"] … return "", 204 ``` ```javascript Node.js (Express) theme={null} import crypto from "node:crypto"; import express from "express"; function verifySignature(body, signature, secret) { const expected = crypto .createHmac("sha256", secret) .update(body) .digest("hex"); if (!signature || expected.length !== signature.length) return false; return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(signature), ); } const app = express(); app.post( "/thunderphone-webhook", express.raw({ type: "application/json" }), (req, res) => { const sig = req.header("X-ThunderPhone-Signature") || ""; if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET)) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); // dispatch on event.type … res.sendStatus(204); }, ); ``` ## Kézbesítési szemantika Ezek a szemantikák a **végpontokra** történő kézbesítésekre vonatkoznak. A régi, egyetlen URL-es webhook egyetlen szinkron kísérletből áll, újrapróbálkozások nélkül. Minden eseményt azonnal egyszer megkísérlünk kézbesíteni. Bármely `2xx` válasz visszaigazolja a kézbesítést. Minden más esetben (nem 2xx, kapcsolati hiba, időtúllépés) az **első kísérlet után 1 perccel, 5 perccel, 30 perccel, 2 órával, 6 órával, 12 órával és 24 órával** újrapróbáljuk — ez 8 kísérletet jelent 24 óra alatt. Ha minden kísérlet sikertelen, a kézbesítés leáll, és a végpont `status="failing"` jelölést kap a [webhook-végpontokban](/hu/webhooks/endpoints). Amint az adattartalmat tartósan fogadta, adjon vissza `2xx` választ; a feldolgozást aszinkron módon végezze. A kézbesítési sorrend legjobb szándék szerinti. A gyakorlatban az eseményeket a kibocsátásuk sorrendjében kézbesítjük, de hiba esetén az újrapróbálkozások megváltoztathatják a sorrendet. Mindig szüntesse meg a duplikációkat, és egyeztesse az adatokat `call_id` / objektumazonosító alapján. A kézbesítés **legalább egyszeri**: egy olyan válasz utáni újrapróbálkozás, amelyet nem észleltünk, megduplázhat egy eseményt. Minden újrapróbálkozás ugyanazt az `event_id` azonosítót tartalmazza, ezért tárolja a feldolgozott azonosítókat, és hagyja ki az ismétlődéseket. Az `event_id` a végpontok között is közös — két, ugyanarra az eseményre feliratkozott végpont ugyanazt az `event_id` azonosítót kapja. A végpontokra történő kézbesítések kísérletenként **30 mp** időtúllépéssel rendelkeznek. A régi útvonalon az élő hívások működését vezérlő blokkoló kérések — a [`telephony.incoming` / `web.incoming`](/hu/webhooks/call-incoming) konfigurációs adatcsere — **10 mp** után időtúllépéssel leállnak, de a lassú válasz késlelteti a hívás fogadását, ezért törekedjen arra, hogy néhány másodpercen belül válaszoljon. A webhook módú [eszközhívás](/hu/tools/overview) 20 mp-et engedélyez. A kimenő webhookok a ThunderPhone felhőalapú IP-címtartományából származnak. Ha a tűzfal engedélyezési listát igényel, lépjen kapcsolatba az ügyfélszolgálattal, és megosztjuk az aktuális tartományokat. ## Választás a régi és a végpont-alapú webhookok között | Funkció | Régi (`/v1/webhook`) | Végpontok (`/v1/developer/webhook-endpoints`) | | -------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------- | | URL-ek száma | 1 szervezetenként | Több szervezetenként | | Eseménylefedettség | Csak `telephony.*` / `web.*` | Mind a 10 eseménytípus | | Eseményszűrő | — | Végpontonként | | Újrapróbálkozások | Nincs | 8 kísérlet 24 óra alatt | | Boríték | `type` + `data` | `type` + `data` + `event_id` | | Titkos kulcs rotációja | Lecseréli az egyetlen titkos kulcsot | Végpontonkénti titkos kulcs | | Letiltás törlés nélkül | — | `status=disabled` | | Állapot láthatósága | — | `active` / `disabled` / `failing` | | Blokkoló konfigurációs adatcsere | Igen ([`telephony.incoming` / `web.incoming`](/hu/webhooks/call-incoming)) | Soha — csak értesítések | | Legjobb felhasználási mód | Dinamikus híváskonfiguráció | Eseményfeldolgozás éles környezetben | Az új integrációknak végpont-alapú webhookokon keresztül kell eseményeket fogadniuk. Csak akkor tartson meg (vagy adjon hozzá) régi URL-t, ha a hívásokat a fogadás időpontjában dinamikusan konfigurálja, vagy webhook módú eszközhívást használ — ezek a kérés/válasz adatcserék csak a régi útvonalon futnak. *** ## Kapcsolódó témák Az összes eseménytípus és adattartalmuk. Több végpont, eseményszűrő és titkos kulcs kezelése. A blokkoló kérés, amelyre a szerverének a hívások konfigurálásához válaszolnia kell. Hívás utáni adattartalom átirattal, felvétellel és mérőszámokkal.