Webhook galiniai taškai

Tvarkykite kelis webhook URL su kiekvienam galiniam taškui skirtais slaptaisiais raktais ir įvykių filtrais.

Galinių taškų pagrindu veikianti webhook sistema leidžia užregistruoti kelias paskirties vietas kiekvienai organizacijai, kurių kiekviena turi savo slaptąjį raktą, savo būseną ir savo prenumeratą į dalį įvykių tipų. Tai rekomenduojamas modelis visoms naujoms integracijoms.

Palyginkite su senąja vieno URL webhook sistema, kuri palaikoma dėl atgalinio suderinamumo, tačiau vienai organizacijai palaiko tik vieną URL.

Galiniai taškai#

Galinio taško objektas#

{
  "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",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Galiojantys įvykių tipai#

events tikrinamas pagal šį tikslų rinkinį — už sąraše nenurodytas reikšmes grąžinamas 400. Kiekvieno tipo naudingosios apkrovos struktūrą žr. Įvykių kataloge.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded, call.data_extracted
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated neturi agento konteksto ir pristatomas tik visos organizacijos galiniams taškams.

voice.ready ir voice.failed negalima pasirinkti aiškiai. Norėdami juos gauti, sukurkite visos organizacijos galinį tašką su events: []. Tuščias įvykių sąrašas gauna kiekvieną palaikomą įvykį, išskyrus telephony.turn ir web.turn, kuriuos būtina pasirinkti aiškiai.

Galinių taškų būsenos#

• active — pristatymai vyksta įprastai.
• disabled — rankiniu būdu pristabdytas naudojant PATCH. Užklausos nesiunčiamos. Mes niekada nekeičiame disabled galinio taško būsenos; sprendimą vėl ją nustatyti į active visada priimate jūs.
• failing — nustatoma automatiškai, kai pristatymas į galinį tašką išnaudoja visą pakartotinių bandymų grafiką (8 bandymai per 24 valandas) ir nė karto negauna 2xx atsakymo. Sugedęs galinis taškas negauna jokio tolesnio srauto. Sutaisę galinį tašką, naudodami PATCH pakeiskite jo būseną atgal į active; pristatymai, kurių pakartotinių bandymų grafikas dar nepasibaigė, tęsiami nuo tos vietos, kur buvo sustoję.

Išvardyti galinius taškus#

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

Grąžina galinių taškų objektų masyvą. Perduokite ?agent_id=42, kad būtų grąžinti tik tam agentui priskirti galiniai taškai.

Agentui priskirti galiniai taškai#

Visos organizacijos galiniai taškai gauna kiekvieną atitinkantį įvykį. Galinis taškas su agent_id gauna tik atitinkančius įvykius, susijusius su skambučiais, kuriuos apdorojo tas agentas; įvykiai be agento konteksto, pvz., alert.triggered, jo niekada nepasiekia. Šiuos galinius taškus taip pat galite kurti ir tvarkyti agento kūrimo priemonės skiltyje Žiniatinklio kabliukai.

Sukurkite galinį tašką#

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"]

Užklausos laukai#

Grąžina 201 Created su galinio taško objektu ir papildomu aukščiausio lygio lauku secret, kuriame pateikiamas neapdorotas pasirašymo raktas — 48 simbolių šešioliktainė eilutė:

{
  "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"
}

Atnaujinkite galinį tašką#

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"]
  }'

Grąžina 200 OK su atnaujintu galinio taško objektu.

Siųsti bandomąjį pristatymą#

Siųskite sintetinį webhook.test įvykį į vieną galinį tašką naudodami įprastą pristatymo srautą, įskaitant kanoninį JSON serializavimą, X-ThunderPhone-Signature, pristatymo registravimą ir pakartotinių bandymų apskaitą. Testas nukreipiamas į pasirinktą galinį tašką, neatsižvelgiant į jo events filtrą.

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

Galinis taškas gauna tokį apvalkalą:

{
  "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"
}

API grąžina 200 OK po pirmojo bandymo, net jei paskirties vieta grąžina klaidą. Norėdami nustatyti pristatymo rezultatą, patikrinkite success, status, response_code ir error:

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

webhook.test yra sintetinis ir jo negalima įtraukti į galinio taško events prenumeratą. Jei pirmasis bandymas nepavyksta, pristatymui taikomas toks pats pakartotinių bandymų grafikas kaip ir įprastiems įvykių pristatymams.

Norėdami sukonfigūruoti aktyviklį pagal tikrą įvykio struktūrą, perduokite pasirenkamą event_type. Pristatymas vis tiek yra sintetinis ir jame yra "sample": true; su skambučiais susijusiuose pavyzdžiuose naudojami call_id: 0 ir agent_id: 0.

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"}'

event_type priima bet kurią reikšmę iš Galiojantys įvykių tipai. Jo nenurodžius išsaugoma bendroji webhook.test elgsena.

Ištrinti galinį tašką#

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

Grąžina 204 No Content. Pristatymas į URL nedelsiant sustabdomas; vykdomi pakartotiniai bandymai nutraukiami.

Derinti pristatymus#

Prieš nuspręsdami, kad žiniatinklio kabliukas nebuvo išsiųstas, patikrinkite GET /v1/developer/webhook-deliveries. Jame rodomi naujausi bandymai iš abiejų žiniatinklio kabliukų sistemų, įskaitant skambučio ID, URL kilmę, HTTP būseną, bandymų skaičių, leidžiamųjų sąraše esančią gedimo kategoriją ir kito pakartotinio bandymo laiką. Jis niekada negrąžina įvykio duomenų, transkripcijos, išsaugoto klaidos teksto, atsakymo turinio ar URL kelio.

Tą pačią naujausią istoriją taip pat galite matyti Agentai → pasirinkite agentą → Žiniatinklio kabliukai → Naujausi pristatymai. Eilutėse rodoma galinio taško etiketė ir URL kilmė, naudota naujausiam bandymui. Tai yra veikimo būsena, o ne nekintamas audito žurnalas: ištrynus galinį tašką taip pat ištrinamos jo pristatymo eilutės.

Jei n8n pateikia 404, pirmiausia patvirtinkite, kad darbo eiga yra aktyvi, priima POST ir naudoja gamybinį žiniatinklio kabliuko URL, o ne bandomąjį URL. 401 arba 403 rodo autentifikavimo arba parašo tikrinimo problemą; laiko limitų viršijimai rodo paskirties vietos delsą arba pasiekiamumą; TLS klaidos rodo sertifikatų grandinės, pagrindinio kompiuterio pavadinimo arba galiojimo pabaigos problemą.

Susiję#