Open in
Končne točke webhookov
Upravljajte več URL-jev webhookov s skrivnostmi za posamezne končne točke in filtri dogodkov.
Sistem webhookov, ki temelji na končnih točkah, vam omogoča registracijo več ciljev za posamezno organizacijo, pri čemer ima vsak svoj skrivni ključ, svoje stanje in svojo naročnino na podmnožico vrst dogodkov. To je priporočeni model za vse nove integracije.
Primerjajte ga s podedovanim webhookom z enim URL-jem, ki je ohranjen zaradi združljivosti za nazaj, vendar podpira le en URL na organizacijo.
Končne točke
| Metoda | Pot | Zahtevana vloga | Opis |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | Prikažite končne točke |
POST | /v1/developer/webhook-endpoints | admin+ | Ustvarite končno točko |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Posodobite oznako / URL / dogodke / stanje |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Izbrišite končno točko |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | Zamenjajte skrivnost za podpisovanje |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Pošljite podpisano testno dostavo |
GET | /v1/developer/webhook-deliveries | admin+ | Preglejte nedavne rezultate dostav končnih točk in podedovanih dostav |
Objekt končne točke
{
"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"
}| Polje | Vrsta | Opis |
|---|---|---|
id | UUID | ID končne točke |
label | niz | Prikazno ime, 1–120 znakov |
url | niz | URL HTTPS; http://localhost je dovoljen za razvoj |
events | polje nizov | Vrste dogodkov, na katere ste naročeni (glejte veljavne vrednosti). Prazno polje vas naroči na vse dogodke, razen na dogodke, ki zahtevajo izrecno naročnino (telephony.turn / web.turn / call.status_changed) |
status | niz | active, disabled (ročno zaustavljeno) ali failing (samodejno nastavljeno, ko dostava porabi 24-urni urnik ponovnih poskusov brez enega samega odgovora 2xx) |
agent_id | celo število | null | Agent, na katerega je omejena ta končna točka; null pomeni za celotno organizacijo |
agent_name | niz | null | Ime omejenega agenta ali null za končno točko za celotno organizacijo |
secret_hint | niz | Prvi 4 in zadnji 4 znaki skrivnosti za podpisovanje s tropičjem (a1b2…9f0e) — dovolj za navzkrižno preverjanje skrivnosti, ki ste jo shranili lokalno, brez razkritja celotne vrednosti |
paused_at | časovni žig | null | Čas, ko je ThunderPhone nastavil končno točko na failing. null, ko je active ali disabled |
pause_last_error | niz | Zadnja napaka dostave, ko je bila končna točka zaustavljena, na primer HTTP 503: Service Unavailable. Prazno, razen če je failing |
pause_undelivered_count | celo število | null | Dogodki, ki niso bili dostavljeni od zadnje uspešne dostave končne točke, prešteti ob njeni zaustavitvi |
created_at, updated_at | časovni žig |
Veljavne vrste dogodkov
events se preverja glede na ta natančni nabor — vrednosti zunaj seznama
vrnejo 400. Za obliko koristnega tovora posamezne vrste glejte katalog dogodkov.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(rezervirano; še ni poslano)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 in phone_number.spam_risk_changed nimata konteksta agenta in
sta dostavljena samo končnim točkam na ravni organizacije.
voice.ready in voice.failed ni mogoče izbrati izrecno. Če jih želite prejemati,
ustvarite končno točko za celotno organizacijo z events: []. Prazen seznam dogodkov
prejema vsak podprti dogodek, razen telephony.turn, web.turn in
call.status_changed, ki jih morate izbrati izrecno.
Stanja končne točke
active— dostave potekajo normalno.disabled— ročno zaustavljeno prekPATCH. Zahteve se ne pošiljajo. Stanja končne točkedisablednikoli ne spremenimo; odločitev o ponovni spremembi vactiveje vedno vaša.failing— nastavljeno samodejno, ko dostava na končno točko porabi celoten razpored ponovnih poskusov (8 poskusov v 24 urah), ne da bi kadar koli prejela odgovor 2xx. Končna točka v stanju napake ne prejema nadaljnjega prometa. Ko se to zgodi, lastnikom in skrbnikom vaše organizacije pošljemo e-poštno sporočilo, nadzorna plošča pa prikaže zaustavljeno končno točko z gumbom Znova aktivirajte. Ko končno točko popravite, zPATCHnjeno stanje spremenite nazaj vactive; dostave, katerih razpored ponovnih poskusov še ni potekel, se nadaljujejo tam, kjer so se ustavile.
Seznam končnih točk
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Vrne polje objektov končne točke.
Posredujte ?agent_id=42, da vrnete samo končne točke, omejene na tega agenta.
Končne točke, omejene na agenta
Končne točke na ravni organizacije prejemajo vsak ujemajoči se dogodek. Končna točka z
agent_id prejema samo ujemajoče se dogodke za klice, ki jih obravnava ta agent;
dogodki brez konteksta agenta, kot je alert.triggered, je nikoli ne dosežejo. Te
končne točke lahko ustvarite in upravljate tudi v razdelku
Spletni kavlji urejevalnika agentov.
Ustvarite končno točko
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"]Polja zahteve
| Polje | Vrsta | Obvezno | Opis |
|---|---|---|---|
label | niz | da | 1–120 znakov |
url | niz | da | URL HTTPS (http je dovoljen samo za localhost / 127.0.0.1) |
events | polje | ne | Prazno/izpuščeno polje se naroči na vse dogodke razen telephony.turn / web.turn / call.status_changed, za katere je potrebna izrecna naročnina. Uporabiti morate vrednosti, navedene v Veljavne vrste dogodkov; dvojniki se odstranijo |
agent_id | celo število | null | ne | Omejite dostavo na agenta v tej organizaciji; za končno točko za celotno organizacijo polje izpustite ali uporabite null |
Vrne 201 Created s posodobljenim objektom končne točke in dodatnim poljem secret na najvišji ravni, ki vsebuje neobdelani ključ za podpisovanje — 48-mestni šestnajstiški niz:
{
"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"
}Posodobite končno točko
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"]
}'| Polje | Vrsta | Opis |
|---|---|---|
label | niz | |
url | niz | |
events | polje | |
status | niz | active ali disabled. Nastavite active, da znova omogočite končno točko, ki jo je strežnik označil kot failing |
agent_id | celo število | null | Nastavite ID agenta, da omejite končno točko, ali null, da jo nastavite za celotno organizacijo |
Vrne 200 OK s posodobljenim objektom končne točke.
Zamenjajte podpisno skrivnost
Zamenjajte podpisno skrivnost končne točke, na primer če se je izgubila ali bi lahko ušla. Uporabite lahko tudi nadzorno ploščo: odprite končno točko v razdelku Integracije → Spletne kljuke (tam so navedene končne točke za celotno organizacijo in agente) in izberite Zamenjajte.
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 '{}'| Polje | Vrsta | Obvezno | Opis |
|---|---|---|---|
include_copies | logična vrednost | ne | Privzeto true. Novo skrivnost dodeli tudi drugim končnim točkam vaše organizacije, ki imajo isti URL in isto trenutno skrivnost, na primer kopijam te končne točke pri drugih agentih, da en prejemnik še naprej preverja z eno skrivnostjo |
Vrne 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| Polje | Vrsta | Opis |
|---|---|---|
endpoint | objekt | Objekt končne točke z novim secret_hint |
secret | niz | Nova podpisna skrivnost. Vrne se samo v tem odgovoru |
rotated_endpoint_ids | polje UUID-jev | Vsaka končna točka, ki zdaj uporablja novo skrivnost |
Pošljite preskusno dostavo
Pošljite sintetični dogodek webhook.test eni končni točki z običajnim
postopkom dostave, vključno s kanonično serializacijo JSON, obema
podpisnima glavama, beleženjem dostave in evidentiranjem ponovnih poskusov.
Preizkus cilja izbrano končno točko ne glede na njen filter events.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Končna točka prejme ovojnico, kot je ta:
{
"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 po prvem poskusu vrne 200 OK, tudi če cilj vrne napako.
Za rezultat dostave preverite success, status, response_code in error:
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}webhook.test je sintetičen in ga ni mogoče dodati naročnini events končne točke.
Če prvi poskus ne uspe, ga ThunderPhone približno eno minuto pozneje enkrat ponovi,
nato pa se ustavi; dostava nato pod Odpravljanje napak pri dostavah
prikaže status: "failed". Preskusna dostava končne točke nikoli ne označi kot
failing.
Če želite konfigurirati sprožilec glede na obliko dejanskega dogodka, podajte izbirni
event_type. Dostava je še vedno sintetična in vsebuje "sample": true;
vzorci, povezani s klici, uporabljajo call_id: 0 in 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 sprejme katero koli vrednost iz Veljavne vrste dogodkov.
Če ga izpustite, se ohrani splošno vedenje webhook.test.
Vzorci za dokončanje klica (telephony.complete, web.complete) in call.data_extracted
vsebujejo agentova lastna polja za zbiranje podatkov v extracted_data.fields,
z nadomestnimi vrednostmi, tako kot njegovi dejanski klici. Za agenta, ki ne zbira
podatkov, vzorec za dokončanje klica pošlje extracted_data: null, tako kot njegovi
dejanski klici, vzorec call.data_extracted pa ima prazna fields (dejanski klici za
takega agenta tega dogodka nikoli ne pošljejo). Vzorčni summary je null, kadar je
povzetek klica agenta izklopljen. Na končni točki agenta vzorec sledi temu agentu; na
končni točki za celotno organizacijo posredujte izbirni agent_id, da ga oblikujete po
enem agentu, ali pa ga izpustite za splošni vzorec.
Izbrišite končno točko
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Vrne 204 No Content. Dostava na URL se takoj ustavi;
ponovni poskusi v teku se opustijo.
Odpravljanje napak pri dostavah
Preden zaključite, da webhook ni bil poslan, preverite
GET /v1/developer/webhook-deliveries.
Prikazuje nedavne poskuse iz obeh sistemov webhookov, vključno z ID-jem klica,
izvorom URL-ja, stanjem HTTP, številom poskusov, kategorijo napake z dovoljenega seznama
in časom naslednjega ponovnega poskusa. Nikoli ne vrne koristnega tovora dogodka,
prepisa, shranjenega besedila napake, telesa odgovora ali poti URL-ja.
Enako nedavno zgodovino lahko vidite tudi v Agenti → izberite agenta → Spletni kavlji → Nedavne dostave. Vrstice prikazujejo oznako končne točke in izvor URL-ja, uporabljen pri najnovejšem poskusu. To je operativno stanje in ne nespremenljiv revizijski dnevnik: z brisanjem končne točke se izbrišejo tudi njene vrstice dostav.
Za napako n8n 404 najprej preverite, ali je potek dela aktiven, sprejema POST in uporablja
produkcijski URL za webhook namesto preskusnega URL-ja. 401 ali 403 kaže na
preverjanje pristnosti ali veljavnosti podpisa; časovne prekoračitve kažejo na zakasnitev
ali razpoložljivost cilja; napake TLS pa na verigo potrdil, ime gostitelja ali potek veljavnosti.