Open in
Koncové body webhookov
Spravujte viacero URL adries webhookov s tajnými kľúčmi a filtrami udalostí pre jednotlivé koncové body.
Systém webhookov založený na koncových bodoch vám umožňuje zaregistrovať viacero cieľov pre každú organizáciu, pričom každý má vlastné tajomstvo, vlastný stav a vlastné predplatné podmnožiny typov udalostí. Tento model sa odporúča pre všetky nové integrácie.
Porovnajte ho so starším webhookom s jednou URL, ktorý sa zachováva kvôli spätnej kompatibilite, ale podporuje iba jednu URL na organizáciu.
Koncové body
| Metóda | Cesta | Požadovaná rola | Popis |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | Zobraziť zoznam endpointov |
POST | /v1/developer/webhook-endpoints | admin+ | Vytvoriť endpoint |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Aktualizovať štítok / URL / udalosti / stav |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Odstrániť endpoint |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | Nahradiť podpisové tajomstvo |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Odoslať podpísané testovacie doručenie |
GET | /v1/developer/webhook-deliveries | admin+ | Skontrolovať nedávne výsledky doručení endpointov a starších doručení |
Objekt koncového bodu
{
"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"
}| Pole | Typ | Popis |
|---|---|---|
id | UUID | ID endpointu |
label | reťazec | Zobrazovaný názov, 1–120 znakov |
url | reťazec | Adresa URL HTTPS; http://localhost je povolená na vývoj |
events | pole reťazcov | Typy odoberaných udalostí (pozrite si platné hodnoty). Prázdne pole odoberá všetky udalosti okrem udalostí iba s explicitným odberom (telephony.turn / web.turn / call.status_changed) |
status | reťazec | active, disabled (pozastavený manuálne) alebo failing (nastaví sa automaticky, keď doručenie vyčerpá svoj 24-hodinový plán opakovaných pokusov bez jedinej odpovede 2xx) |
agent_id | celé číslo | null | Agent, na ktorého je tento endpoint obmedzený; null znamená celú organizáciu |
agent_name | reťazec | null | Názov agenta, na ktorého je endpoint obmedzený, alebo null pre endpoint celej organizácie |
secret_hint | reťazec | Prvé 4 a posledné 4 znaky podpisového tajomstva s výpustkou (a1b2…9f0e) — postačuje na porovnanie s tajomstvom, ktoré ste uložili lokálne, bez odhalenia celej hodnoty |
paused_at | časová pečiatka | null | Čas, keď ThunderPhone nastavil endpoint na failing. null, keď je active alebo disabled |
pause_last_error | reťazec | Posledná chyba doručenia pri pozastavení endpointu, napríklad HTTP 503: Service Unavailable. Prázdne, ak nejde o failing |
pause_undelivered_count | celé číslo | null | Udalosti nedoručené od posledného úspešného doručenia endpointu, spočítané pri jeho pozastavení |
created_at, updated_at | časová pečiatka |
Platné typy udalostí
events sa overuje podľa tejto presnej množiny — hodnoty mimo zoznamu
vrátia 400. Tvar dát pre každý typ nájdete v katalógu udalostí.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(rezervované; zatiaľ sa neodosiela)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 a phone_number.spam_risk_changed nemajú kontext agenta a
doručujú sa iba do koncových bodov platných pre celú organizáciu.
voice.ready a voice.failed nemožno vybrať explicitne. Ak ich chcete prijímať,
vytvorte koncový bod pre celú organizáciu s events: []. Prázdny zoznam udalostí
prijíma všetky podporované udalosti okrem telephony.turn, web.turn a
call.status_changed, ktoré je nutné vybrať explicitne.
Stavy koncového bodu
active— doručovania prebiehajú normálne.disabled— manuálne pozastavený prostredníctvomPATCH. Neodosielajú sa žiadne požiadavky. Stav endpointudisablednikdy nemeníme; jeho prepnutie späť naactiveje vždy na vás.failing— nastaví sa automaticky, keď doručovanie do endpointu vyčerpá celý plán opakovaných pokusov (8 pokusov počas 24 hodín) bez získania odpovede 2xx. Endpoint v stave zlyhania už neprijíma ďalšiu prevádzku. Keď k tomu dôjde, vlastníkom a administrátorom vašej organizácie odošleme e-mail a dashboard zobrazí pozastavený endpoint s tlačidlom Znova aktivovať. Keď endpoint opravíte, pomocouPATCHzmeňte jeho stav späť naactive; doručovania, ktorým sa plán opakovaných pokusov ešte nevyčerpal, budú pokračovať tam, kde skončili.
Zoznam koncových bodov
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Vráti pole objektov koncového bodu.
Ak chcete vrátiť iba koncové body obmedzené na daného agenta, zadajte ?agent_id=42.
Koncové body obmedzené na agenta
Koncové body platné v celej organizácii prijímajú každú zodpovedajúcu udalosť. Koncový bod s
agent_id prijíma iba zodpovedajúce udalosti hovorov spracovaných daným agentom;
udalosti bez kontextu agenta, ako napríklad alert.triggered, sa k nemu nikdy nedostanú. Tieto
koncové body môžete tiež vytvárať a spravovať v sekcii
Webhooky nástroja na tvorbu agentov.
Vytvorte koncový bod
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"]Polia požiadavky
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
label | reťazec | áno | 1–120 znakov |
url | reťazec | áno | URL HTTPS (http je povolené iba pre localhost / 127.0.0.1) |
events | pole | nie | Prázdna alebo vynechaná hodnota aktivuje odber všetkých udalostí okrem telephony.turn / web.turn / call.status_changed, ktoré vyžadujú explicitné prihlásenie na odber. Musíte použiť hodnoty uvedené v časti Platné typy udalostí; duplicity sa odstránia |
agent_id | celé číslo | null | nie | Obmedzte doručovanie na agenta v tejto organizácii; pre koncový bod pre celú organizáciu hodnotu vynechajte alebo použite null |
Vráti 201 Created s objektom koncového bodu a dodatočným
poľom secret na najvyššej úrovni obsahujúcim nespracovaný podpisový kľúč —
48-znakový hexadecimálny reťazec:
{
"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"
}Aktualizujte koncový bod
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"]
}'| Pole | Typ | Popis |
|---|---|---|
label | reťazec | |
url | reťazec | |
events | pole | |
status | reťazec | active alebo disabled. Nastavte active, aby ste znova povolili koncový bod, ktorý server označil ako failing |
agent_id | celé číslo | null | Nastavte ID agenta na obmedzenie koncového bodu alebo null, aby platil pre celú organizáciu |
Vráti 200 OK s aktualizovaným objektom koncového bodu.
Obnovte podpisový tajný kľúč
Nahraďte podpisové tajomstvo koncového bodu, napríklad ak sa stratilo alebo mohlo uniknúť. Môžete tiež použiť ovládací panel: otvorte koncový bod v časti Integrácie → Webhooky (sú tam uvedené koncové body organizácie aj agentov) a vyberte možnosť Rotovať.
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 '{}'| Pole | Typ | Povinné | Popis |
|---|---|---|---|
include_copies | boolean | nie | Predvolene true. Nový tajný kľúč sa poskytne aj ostatným endpointom vašej organizácie, ktoré majú rovnakú adresu URL a rovnaký aktuálny tajný kľúč, napríklad kópiám tohto endpointu pri iných agentoch, aby jeden prijímač naďalej overoval pomocou jedného tajného kľúča |
Vracia 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| Pole | Typ | Popis |
|---|---|---|
endpoint | object | Objekt Endpoint s novým secret_hint |
secret | string | Nový podpisový tajný kľúč. Vracia sa iba v tejto odpovedi |
rotated_endpoint_ids | pole UUID | Každý endpoint, ktorý teraz používa nový tajný kľúč |
Odoslanie testovacieho doručenia
Odošlite syntetickú udalosť webhook.test do jedného endpointu pomocou štandardného
procesu doručenia vrátane kanonickej serializácie JSON, oboch
hlavičiek podpisu, zaznamenania doručenia a evidencie opakovaných pokusov.
Test sa zameria na vybraný endpoint bez ohľadu na jeho filter events.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Koncový bod dostane obálku podobnú tejto:
{
"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 vráti 200 OK po prvom pokuse, aj keď cieľ vráti chybu.
Výsledok doručenia skontrolujte v poliach success, status, response_code a error:
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}webhook.test je syntetická udalosť a nemožno ju pridať do odberu events
koncového bodu. Ak prvý pokus zlyhá, ThunderPhone ho približne o minútu zopakuje
ešte raz a potom skončí; doručenie potom v časti Ladenie doručení
zobrazí status: "failed". Testovacie doručenie nikdy neoznačí koncový bod ako
failing.
Ak chcete nakonfigurovať spúšťač podľa štruktúry skutočnej udalosti, odovzdajte voliteľný
parameter event_type. Doručenie je stále syntetické a obsahuje "sample": true;
vzorky súvisiace s hovormi používajú call_id: 0 a 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 prijíma ľubovoľnú hodnotu zo zoznamu Platné typy udalostí.
Ak ho vynecháte, zachová sa všeobecné správanie webhook.test.
Vzorky dokončenia hovoru (telephony.complete, web.complete) a call.data_extracted
obsahujú vlastné polia agenta na zhromaždenie údajov v časti
extracted_data.fields so zástupnými hodnotami rovnako ako jeho skutočné hovory. Pre
agenta, ktorý nezhromažďuje žiadne údaje, vzorka dokončenia hovoru odosiela
extracted_data: null rovnako ako jeho skutočné hovory a vzorka call.data_extracted
má prázdne fields (skutočné hovory pre takého agenta túto udalosť nikdy neodosielajú).
Pole summary vzorky je null, keď je súhrn hovoru agenta vypnutý. Na koncovom bode
agenta vzorka zodpovedá tomuto agentovi; na koncovom bode pre celú organizáciu
zadajte voliteľné agent_id, aby sa prispôsobila konkrétnemu agentovi, alebo ho vynechajte
pre všeobecnú vzorku.
Odstránenie koncového bodu
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Vráti 204 No Content. Doručovanie na URL sa okamžite zastaví;
prebiehajúce opakované pokusy sa zrušia.
Ladenie doručení
Predtým, než usúdite, že webhook nebol odoslaný, skontrolujte
GET /v1/developer/webhook-deliveries.
Zobrazuje nedávne pokusy z oboch webhook systémov vrátane ID hovoru,
pôvodu URL, stavu HTTP, počtu pokusov, kategórie povolenej chyby a času
nasledujúceho opakovania. Nikdy nevracia payload udalosti, prepis, uložený text chyby,
telo odpovede ani cestu URL.
Rovnakú nedávnu históriu nájdete aj v Agenti → vyberte agenta → Webhooky → Nedávne doručenia. Riadky zobrazujú označenie koncového bodu a pôvod URL použitý pri najnovšom pokuse. Ide o prevádzkový stav, nie nemenný auditný záznam: odstránením koncového bodu sa odstránia aj jeho riadky doručení.
Pri chybe n8n 404 najprv potvrďte, že pracovný postup je aktívny, prijíma POST a používa
produkčnú URL webhooku namiesto testovacej URL. Chyba 401 alebo 403 naznačuje problém
s autentifikáciou alebo overením podpisu; časové limity naznačujú latenciu
alebo dostupnosť cieľa; chyby TLS naznačujú problém s reťazcom certifikátov, názvom hostiteľa alebo expiráciou.