Open in
Webhook galiniai taškai
Valdykite kelis webhook URL su kiekvieno galinio taško slaptaisiais raktais ir įvykių filtrais.
Galinių taškų pagrindu veikianti žiniatinklio kabliukų sistema leidžia užregistruoti kelias paskirties vietas kiekvienai organizacijai, kiekvieną su atskira paslaptimi, atskira būsena ir atskira pasirinktų įvykių tipų prenumerata. Tai rekomenduojamas modelis visoms naujoms integracijoms.
Palyginkite su senąja vieno URL žiniatinklio kabliuko sistema, kuri išlaikoma siekiant atgalinio suderinamumo, tačiau palaiko tik vieną URL vienai organizacijai.
Galiniai taškai
| Metodas | Kelias | Reikalingas vaidmuo | Aprašymas |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | Išvardyti galinius taškus |
POST | /v1/developer/webhook-endpoints | admin+ | Sukurti galinį tašką |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Atnaujinti etiketę / URL / įvykius / būseną |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Ištrinti galinį tašką |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | Pakeisti pasirašymo slaptąjį raktą |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Siųsti pasirašytą bandomąjį pristatymą |
GET | /v1/developer/webhook-deliveries | admin+ | Peržiūrėti naujausius galinių taškų ir senųjų pristatymų rezultatus |
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",
"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"
}| Laukas | Tipas | Aprašas |
|---|---|---|
id | UUID | Galinio taško ID |
label | eilutė | Rodomas pavadinimas, 1–120 simbolių |
url | eilutė | HTTPS URL; http://localhost leidžiama kūrimui |
events | eilučių masyvas | Prenumeruojami įvykių tipai (žr. galiojančias reikšmes). Tuščias masyvas prenumeruoja visus įvykius, išskyrus tik aiškiai nurodomus įvykius (telephony.turn / web.turn / call.status_changed) |
status | eilutė | active, disabled (pristabdyta rankiniu būdu) arba failing (nustatoma automatiškai, kai pristatant įvykį išnaudojamas 24 val. pakartotinių bandymų tvarkaraštis negavus nė vieno 2xx atsakymo) |
agent_id | sveikasis skaičius | null | Agentas, kuriam priskirtas šis galinis taškas; null reiškia visos organizacijos galinį tašką |
agent_name | eilutė | null | Priskirto agento pavadinimas arba null, jei galinis taškas skirtas visai organizacijai |
secret_hint | eilutė | Pirmi 4 ir paskutiniai 4 pasirašymo paslapties simboliai su daugtaškiu (a1b2…9f0e) — pakanka susieti su vietoje išsaugota paslaptimi neatskleidžiant visos reikšmės |
paused_at | laiko žyma | null | Kada ThunderPhone nustatė galinio taško būseną į failing. null, kol būsena yra active arba disabled |
pause_last_error | eilutė | Paskutinė pristatymo klaida, kai galinis taškas buvo pristabdytas, pvz., HTTP 503: Service Unavailable. Tuščia, nebent būsena yra failing |
pause_undelivered_count | sveikasis skaičius | null | Įvykiai, nepristatyti nuo paskutinio sėkmingo galinio taško pristatymo, suskaičiuoti jį pristabdžius |
created_at, updated_at | laiko žyma |
Galiojantys įvykių tipai
events tikrinamas pagal šį tikslų sąrašą — už sąrašo ribų esančios reikšmės
grąžina 400. Kiekvieno tipo naudingojo krūvio struktūrą žr. Įvykių kataloge.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(rezervuota; dar nesiunčiama)scheduled.skipped,scheduled.failedcall.graded,call.data_extracted,call.transfer_completed,call.status_changedcampaign.completedissue.reported,issue.escalatedtest-call.completedalert.triggeredphone_number.spam_risk_changed
issue.escalated ir phone_number.spam_risk_changed neturi agento konteksto ir
yra siunčiami tik į visos organizacijos galinius taškus.
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, web.turn ir
call.status_changed, kuriuos būtina pasirinkti aiškiai.
Galinių taškų būsenos
active— pristatymai vyksta įprastai.disabled— rankiniu būdu pristabdytas naudojantPATCH. Užklausos nesiunčiamos. Mes niekada nekeičiamedisabledgalinio taško būsenos; grąžinti ją įactivevisada sprendžiate jūs.failing— nustatoma automatiškai, kai pristatymas į galinį tašką išnaudoja visą pakartotinių bandymų tvarkaraštį (8 bandymai per 24 valandas) nė karto negavęs 2xx atsakymo. Į nepavykstantį galinį tašką daugiau srauto nesiunčiama. Kai taip nutinka, el. paštu informuojame jūsų organizacijos savininkus ir administratorius, o valdymo skydelyje pristabdytas galinis taškas rodomas su mygtuku Reaktyvinti. Ištaisę galinį tašką, naudokitePATCH, kad grąžintumėte jo būseną įactive; pristatymai, kurių pakartotinių bandymų tvarkaraštis dar nepasibaigė, tęsiami nuo vietos, kur buvo sustoję.
Galinių taškų sąrašas
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 skambučių, kuriuos tvarko tas agentas, įvykius;
į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 kabliai.
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
| Laukas | Tipas | Privalomas | Aprašas |
|---|---|---|---|
label | eilutė | taip | 1–120 simbolių |
url | eilutė | taip | HTTPS URL (http leidžiama naudoti tik su localhost / 127.0.0.1) |
events | masyvas | ne | Tuščias arba nenurodytas masyvas užprenumeruoja visus įvykius, išskyrus telephony.turn / web.turn / call.status_changed, kuriems reikia aiškios prenumeratos. Būtina naudoti reikšmes, nurodytas skiltyje Galiojantys įvykių tipai; dublikatai pašalinami |
agent_id | sveikasis skaičius | null | ne | Apriboja pristatymą šios organizacijos agentui; praleiskite arba naudokite null, jei galinis taškas taikomas visai organizacijai |
Grąžina 201 Created su galinio taško objektu ir papildomu
aukščiausio lygmens secret lauku, kuriame yra 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"]
}'| Laukas | Tipas | Aprašymas |
|---|---|---|
label | eilutė | |
url | eilutė | |
events | masyvas | |
status | eilutė | active arba disabled. Nustatykite active, kad iš naujo įjungtumėte galinį tašką, kurį serveris pažymėjo kaip failing |
agent_id | sveikasis skaičius | null | Nustatykite agento ID, kad apribotumėte galinį tašką, arba null, kad jis būtų skirtas visai organizacijai |
Grąžina 200 OK su atnaujintu galinio taško objektu.
Pasukite pasirašymo paslaptį
Pakeiskite galinio taško pasirašymo slaptąjį raktą, pavyzdžiui, jei jis buvo prarastas arba galėjo nutekėti. Taip pat galite naudoti valdymo skydelį: atidarykite galinį tašką skiltyje Integracijos → Žiniatinklio kabliukai (ten pateikiami tiek visos organizacijos, tiek agentų galiniai taškai) ir pasirinkite Keisti.
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 '{}'| Laukas | Tipas | Privaloma | Aprašymas |
|---|---|---|---|
include_copies | loginė reikšmė | ne | Numatytoji reikšmė true. Nauja paslaptis taip pat suteikiama kitiems jūsų organizacijos galiniams taškams, turintiems tą patį URL ir tą pačią dabartinę paslaptį, pavyzdžiui, šio galinio taško kopijoms kituose agentuose, kad vienas gavėjas toliau tikrintų naudodamas vieną paslaptį |
Grąžina 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| Laukas | Tipas | Aprašymas |
|---|---|---|
endpoint | objektas | Galinio taško objektas su nauju secret_hint |
secret | eilutė | Nauja pasirašymo paslaptis. Grąžinama tik šiame atsakyme |
rotated_endpoint_ids | UUID masyvas | Kiekvienas galinis taškas, dabar naudojantis naują paslaptį |
Siųsti bandomąjį pristatymą
Išsiųskite sintetinį webhook.test įvykį į vieną galinį tašką naudodami įprastą
pristatymo procesą, įskaitant kanoninį JSON serializavimą, abi
parašo antraštes, pristatymo įrašymą 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ą. Pristatymo rezultatą tikrinkite pagal 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 pridėti prie galinio taško events
prenumeratos. Jei pirmasis bandymas nepavyksta, ThunderPhone maždaug po
vienos minutės jį pakartoja vieną kartą ir tada sustoja; pristatymas tuomet rodo status: "failed"
skiltyje Pristatymų derinimas. Bandomasis pristatymas niekada nepažymi
galinio taško kaip failing.
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š Galiojančių įvykių tipų.
Jo nenurodžius išlaikoma bendrinė webhook.test elgsena.
Skambučio užbaigimo (telephony.complete, web.complete) ir call.data_extracted
pavyzdžiuose agento duomenų rinkimo laukai pateikiami skiltyje
extracted_data.fields su vietos rezervavimo reikšmėmis, kaip ir tikruose jo skambučiuose. Agentui,
kuris nerenka jokių duomenų, skambučio užbaigimo pavyzdys siunčia
extracted_data: null, kaip ir tikri jo skambučiai, o call.data_extracted
pavyzdyje fields yra tuščias (tikri skambučiai tokiam agentui šio įvykio niekada nesiunčia).
Pavyzdžio summary yra null, kai agento skambučio suvestinė išjungta. Agento
galiniame taške pavyzdys atitinka tą agentą; visos organizacijos galiniame
taške perduokite pasirenkamą agent_id, kad jis būtų suformuotas pagal vieną agentą, arba jo nenurodykite,
kad būtų naudojamas bendrasis pavyzdys.
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;
vykdomų pakartotinių bandymų atsisakoma.
Pristatymų derinimas
Prieš nuspręsdami, kad webhook nebuvo išsiųstas, patikrinkite
GET /v1/developer/webhook-deliveries.
Čia rodomi naujausi bandymai iš abiejų webhook sistemų, įskaitant skambučio
identifikatorių, URL kilmę, HTTP būseną, bandymų skaičių, leidžiamųjų sąraše esančią nesėkmės kategoriją ir kito
pakartotinio bandymo laiką. Čia niekada negrąžinamas įvykio turinys, transkripcija, išsaugotas klaidos tekstas,
atsakymo turinys ar URL kelias.
Tą pačią naujausią istoriją taip pat galite matyti skiltyje Agentai → pasirinkite agentą → Žiniatinklio kabliukai → Naujausi pristatymai. Eilutėse rodomos galinio taško etiketė ir URL kilmė, naudota paskutiniame bandyme. Tai yra veikimo būsena, o ne nekintamas audito žurnalas: ištrynus galinį tašką taip pat ištrinamos jo pristatymų eilutės.
Jei n8n grąžina 404, pirmiausia patvirtinkite, kad darbo eiga aktyvi, priima POST ir naudoja
gamybinį webhook URL, o ne bandomąjį URL. 401 arba 403 nurodo
autentifikavimo arba parašo tikrinimo problemą; laiko limitų viršijimas nurodo paskirties vietos delsą
arba pasiekiamumą; TLS klaidos nurodo sertifikatų grandinę, pagrindinio kompiuterio pavadinimą arba galiojimo pabaigą.