Webhook-végpontok

Több webhook URL kezelése végpontonkénti titkos kulcsokkal és eseményszűrőkkel.

A végpontalapú webhookrendszerrel szervezetenként több célhelyet is regisztrálhat, amelyek mindegyike saját titkos kulccsal, saját állapottal és az eseménytípusok egy részhalmazára szóló saját előfizetéssel rendelkezik. Ez az ajánlott modell minden új integrációhoz.

Hasonlítsa össze a régi, egyetlen URL-es webhookkal, amelyet a visszamenőleges kompatibilitás érdekében tartunk fenn, de szervezetenként csak egy URL-t támogat.

Végpontok#

Végpontobjektum#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Érvényes eseménytípusok#

Az events mezőt pontosan ezen készlet alapján ellenőrizzük — a listán kívüli értékek 400 választ adnak vissza. Az egyes típusok hasznos adatainak szerkezetét az Eseménykatalógusban találja.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (fenntartva; még nincs kibocsátva)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

Az issue.escalated nem rendelkezik AI-ügynök-kontextussal, és csak szervezetszintű végpontokhoz kerül kézbesítésre.

A voice.ready és a voice.failed nem választható ki kifejezetten. Ezek fogadásához hozzon létre egy szervezetszintű végpontot events: [] értékkel. Az üres eseménylista minden támogatott eseményt fogad, kivéve a telephony.turn és web.turn eseményeket, amelyeket kifejezetten kell kiválasztani.

Végpontállapotok#

• active — a kézbesítések normálisan zajlanak.
• disabled — PATCH használatával manuálisan szüneteltetve. Nem küldünk kéréseket. Soha nem módosítjuk egy disabled végpont állapotát; az active állapotba való visszaállítás mindig Önön múlik.
• failing — automatikusan beállítjuk, ha egy végpontra történő kézbesítés a teljes újrapróbálkozási ütemezést (8 próbálkozás 24 óra alatt) felhasználja anélkül, hogy valaha 2xx választ kapna. A hibás végpont nem kap további forgalmat. Amikor ez történik, e-mailt küldünk a szervezet tulajdonosainak és rendszergazdáinak, az irányítópult pedig az újraaktiválás gombbal jeleníti meg a szüneteltetett végpontot. Miután a végpont javítva lett, PATCH használatával állítsa vissza az állapotát active értékre; azok a kézbesítések, amelyeknek az újrapróbálkozási ütemezése még nem járt le, onnan folytatódnak, ahol abbamaradtak.

Végpontok listázása#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Végpontobjektumok tömbjét adja vissza. Adja át a ?agent_id=42 paramétert, hogy csak az adott AI-ügynökhöz tartozó végpontokat kapja vissza.

AI-ügynökhöz tartozó végpontok#

A szervezetszintű végpontok minden egyező eseményt fogadnak. Az agent_id értékkel rendelkező végpont csak az adott AI-ügynök által kezelt hívásokhoz tartozó egyező eseményeket fogadja; az AI-ügynök-kontextus nélküli események, például az alert.triggered, soha nem érik el. Ezeket a végpontokat az AI-ügynökszerkesztő Webhookok szakaszában is létrehozhatja és kezelheti.

Végpont létrehozása#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Kérésmezők#

201 Created választ ad vissza a Végpontobjektummal, valamint egy további felső szintű secret mezővel, amely a nyers aláírókulcsot — egy 48 karakteres hexadecimális karakterláncot — tartalmazza:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Végpont frissítése#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

200 OK választ ad vissza a frissített Végpontobjektummal.

Az aláírási titok cseréje#

Cserélje le egy végpont aláírási titkát, például ha elveszett vagy kiszivároghatott. AI-ügynökhöz tartozó végpont esetén a vezérlőpultot is használhatja: nyissa meg az ügynök Webhookok szakaszát, és válassza a végpontnál a Titok újragenerálása lehetőséget. A szervezetre kiterjedő végpontok titkát az API-n keresztül cserélheti le.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 OK választ ad vissza:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Tesztkézbesítés küldése#

Küldjön szintetikus webhook.test eseményt egy végpontra a normál kézbesítési folyamaton keresztül, beleértve a kanonikus JSON-szerializálást, mindkét aláírási fejlécet, a kézbesítés rögzítését és az újrapróbálkozások nyilvántartását. A teszt a kiválasztott végpontot célozza meg annak events szűrőjétől függetlenül.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

A végpont a következő eseményburkolatot kapja:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

Az API az első próbálkozás után 200 OK választ ad vissza, még akkor is, ha a cél hibát ad vissza. A kézbesítés eredményéhez vizsgálja meg a success, status, response_code és error értékeket:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

A webhook.test szintetikus, és nem adható hozzá egy végpont events feliratkozásához. Ha az első próbálkozás sikertelen, a ThunderPhone körülbelül egy perccel később egyszer újrapróbálja, majd leáll; a kézbesítés ezután status: "failed" állapotot mutat a Kézbesítések hibakeresése részben. A tesztkézbesítés soha nem jelöli a végpontot failing állapotúként.

Valódi eseménystruktúrához való kiváltó konfigurálásához adjon meg egy opcionális event_type értéket. A kézbesítés továbbra is szintetikus marad, és tartalmazza a "sample": true értéket; a híváshoz kapcsolódó minták a call_id: 0 és agent_id: 0 értékeket használják.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

Az event_type a Érvényes eseménytípusok bármely értékét elfogadja. Az érték elhagyása megőrzi az általános webhook.test viselkedést.

Végpont törlése#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content választ ad vissza. Az URL-re történő kézbesítés azonnal leáll; a folyamatban lévő újrapróbálások megszakadnak.

Kézbesítések hibakeresése#

Mielőtt arra következtetne, hogy egy webhookot nem küldtek el, vizsgálja meg a GET /v1/developer/webhook-deliveries végpontot. Ez mindkét webhookrendszer legutóbbi próbálkozásait mutatja, beleértve a hívásazonosítót, az URL-eredetet, a HTTP-állapotot, a próbálkozások számát, az engedélyezési listán szereplő hibakategóriát és a következő újrapróbálás idejét. Soha nem adja vissza az eseményadatokat, az átiratot, a tárolt hibaszöveget, a válasz törzsét vagy az URL-útvonalat.

Ugyanezt a közelmúltbeli előzményt a Ügynökök → Válasszon ki egy ügynököt → Webhookok → Legutóbbi kézbesítések menüpontban is megtekintheti. A sorok a végpont címkéjét és a legutóbbi próbálkozás által használt URL-eredetet mutatják. Ez működési állapot, nem pedig megváltoztathatatlan auditnapló: egy végpont törlése a hozzá tartozó kézbesítési sorokat is törli.

n8n 404 esetén először ellenőrizze, hogy a munkafolyamat aktív, fogad POST kéréseket, és a teszt URL helyett az éles webhook URL-t használja. A 401 vagy 403 hitelesítési vagy aláírás-ellenőrzési problémára utal; az időtúllépések a cél késleltetésére vagy elérhetőségére; a TLS-hibák a tanúsítványláncra, a gépnévre vagy a lejáratra utalnak.

Kapcsolódó#