Open in
Krajnje točke webhooka
Upravljajte višestrukim URL-ovima webhooka s tajnama za svaku krajnju točku i filtrima događaja.
Sustav webhookova temeljen na krajnjim točkama omogućuje vam registraciju više odredišta po organizaciji, pri čemu svako ima vlastitu tajnu, vlastiti status i vlastitu pretplatu na podskup vrsta događaja. Ovo je preporučeni model za sve nove integracije.
Usporedite sa zastarjelim webhookom s jednim URL-om, koji se zadržava radi kompatibilnosti sa starijim verzijama, ali podržava samo jedan URL po organizaciji.
Krajnje točke
| Metoda | Putanja | Potrebna uloga | Opis |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | Prikažite krajnje točke |
POST | /v1/developer/webhook-endpoints | admin+ | Izradite krajnju točku |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Ažurirajte oznaku / URL / događaje / status |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Izbrišite krajnju točku |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | Zamijenite tajnu za potpisivanje |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Pošaljite potpisanu probnu isporuku |
GET | /v1/developer/webhook-deliveries | admin+ | Pregledajte nedavne rezultate isporuke za krajnje točke i zastarjeli sustav |
Objekt krajnje 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 krajnje točke |
label | string | Prikazni naziv, 1–120 znakova |
url | string | HTTPS URL; http://localhost dopušten za razvoj |
events | niz stringova | Vrste događaja na koje ste pretplaćeni (pogledajte valjane vrijednosti). Prazan niz pretplaćuje na sve događaje osim događaja samo uz izričitu pretplatu (telephony.turn / web.turn / call.status_changed) |
status | string | active, disabled (ručno pauzirano) ili failing (automatski postavljeno kada isporuka iscrpi raspored ponovnih pokušaja od 24 h bez ijednog odgovora 2xx) |
agent_id | integer | null | Agent za kojeg je ova krajnja točka ograničena; null znači za cijelu organizaciju |
agent_name | string | null | Naziv obuhvaćenog agenta ili null za krajnju točku na razini organizacije |
secret_hint | string | Prva 4 i zadnja 4 znaka tajne vrijednosti za potpisivanje s trotočkom (a1b2…9f0e) — dovoljno za usporedbu s tajnom vrijednošću koju ste lokalno spremili bez otkrivanja pune vrijednosti |
paused_at | timestamp | null | Kada je ThunderPhone postavio krajnju točku na failing. null dok je active ili disabled |
pause_last_error | string | Posljednja pogreška isporuke kada je krajnja točka pauzirana, na primjer HTTP 503: Service Unavailable. Prazno osim ako je failing |
pause_undelivered_count | integer | null | Događaji koji nisu isporučeni od posljednje uspješne isporuke krajnje točke, izbrojeni kada je pauzirana |
created_at, updated_at | timestamp |
Valjane vrste događaja
events se provjerava prema ovom točnom skupu — vrijednosti izvan popisa
vraćaju 400. Pogledajte katalog događaja za strukturu
korisnog tereta svake vrste.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(rezervirano; još se ne šalje)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 i phone_number.spam_risk_changed nemaju kontekst agenta i
isporučuju se samo krajnjim točkama na razini organizacije.
voice.ready i voice.failed nije moguće izričito odabrati. Da biste ih primali, izradite krajnju točku za cijelu organizaciju s events: []. Prazan popis događaja prima svaki podržani događaj osim telephony.turn, web.turn i call.status_changed, koje je potrebno izričito odabrati.
Statusi krajnjih točaka
active— isporuke se odvijaju normalno.disabled— ručno pauzirano putemPATCH. Zahtjevi se ne šalju. Nikada ne mijenjamo status krajnje točkedisabled; vraćanje naactiveuvijek je vaša odluka.failing— automatski se postavlja kada isporuka na krajnju točku potroši cijeli raspored ponovnih pokušaja (8 pokušaja tijekom 24 sata) bez ijednog odgovora 2xx. Krajnja točka sa statusom failing više ne prima promet. Kada se to dogodi, e-poštom obavještavamo vlasnike i administratore vaše organizacije, a nadzorna ploča prikazuje pauziranu krajnju točku s gumbom Ponovno aktivirajte. Nakon što se krajnja točka ispravi, status joj putemPATCHvratite naactive; isporuke čiji raspored ponovnih pokušaja još nije istekao nastavljaju tamo gdje su stale.
Popis krajnjih točaka
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Vraća polje objekata krajnjih točaka.
Proslijedite ?agent_id=42 za vraćanje samo krajnjih točaka ograničenih na tog agenta.
Krajnje točke ograničene na agenta
Krajnje točke za cijelu organizaciju primaju svaki odgovarajući događaj. Krajnja točka s
agent_id prima samo odgovarajuće događaje za pozive kojima upravlja taj agent;
događaji bez konteksta agenta, kao što je alert.triggered, nikada je ne dosežu. Ove
krajnje točke možete i stvarati te upravljati njima iz odjeljka
Webhookovi u izrađivaču agenta.
Izradite krajnju točku
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 zahtjeva
| Polje | Vrsta | Obavezno | Opis |
|---|---|---|---|
label | niz znakova | da | 1–120 znakova |
url | niz znakova | da | HTTPS URL (http je dopušten samo za localhost / 127.0.0.1) |
events | niz | ne | Prazno/izostavljeno pretplaćuje na sve događaje osim telephony.turn / web.turn / call.status_changed, za koje je potrebna izričita pretplata. Moraju se koristiti vrijednosti navedene u Valjane vrste događaja; duplikati se uklanjaju |
agent_id | cijeli broj | null | ne | Ograničite isporuku na agenta u ovoj organizaciji; izostavite ili upotrijebite null za krajnju točku na razini organizacije |
Vraća 201 Created s ažuriranim objektom krajnje točke i dodatnim poljem secret najviše razine koje sadrži neobrađeni ključ za potpisivanje — heksadecimalni niz od 48 znakova:
{
"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"
}Ažurirajte krajnju točku
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 znakova | |
url | niz znakova | |
events | polje | |
status | niz znakova | active ili disabled. Postavite active da biste ponovno omogućili krajnju točku koju je poslužitelj označio kao failing |
agent_id | cijeli broj | null | Postavite ID agenta da biste ograničili krajnju točku ili null da bi bila na razini cijele organizacije |
Vraća 200 OK s ažuriranim objektom krajnje točke.
Rotirajte tajnu za potpisivanje
Zamijenite tajnu za potpisivanje krajnje točke, primjerice ako je izgubljena ili je možda procurila. Možete upotrijebiti i nadzornu ploču: otvorite krajnju točku u odjeljku Integracije → Web-dojave (ondje su navedene krajnje točke za cijelu organizaciju i agente) i odaberite Rotirajte.
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 | Obavezno | Opis |
|---|---|---|---|
include_copies | boolean | ne | Zadano je true. Novu tajnu također dodjeljuje drugim krajnjim točkama vaše organizacije koje imaju isti URL i istu trenutačnu tajnu, poput kopija ove krajnje točke na drugim agentima, tako da jedan primatelj nastavi provjeravati s jednom tajnom |
Vraća 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| Polje | Vrsta | Opis |
|---|---|---|
endpoint | object | Objekt krajnje točke s novim secret_hint |
secret | string | Nova tajna za potpisivanje. Vraća se samo u ovom odgovoru |
rotated_endpoint_ids | polje UUID-ova | Svaka krajnja točka koja sada upotrebljava novu tajnu |
Pošaljite probnu isporuku
Pošaljite sintetički događaj webhook.test na jednu krajnju točku putem standardnog
tijeka isporuke, uključujući kanonsku JSON serijalizaciju, oba
zaglavlja potpisa, bilježenje isporuke i evidenciju ponovnih pokušaja.
Test cilja odabranu krajnju točku bez obzira na njezin filtar events.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Krajnja točka prima omotnicu poput ove:
{
"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 vraća 200 OK nakon prvog pokušaja, čak i ako odredište
vrati pogrešku. Pregledajte success, status, response_code i error
za ishod isporuke:
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}webhook.test je sintetički i ne može se dodati pretplati krajnje točke na
events. Ako prvi pokušaj ne uspije, ThunderPhone ga ponovno pokušava jednom otprilike
jednu minutu kasnije, a zatim prestaje; isporuka tada prikazuje status: "failed"
u odjeljku Otklanjanje pogrešaka isporuka. Probna isporuka nikada ne označava
krajnju točku kao failing.
Za konfiguriranje okidača za stvarni oblik događaja proslijedite neobavezni
event_type. Isporuka je i dalje sintetička i sadrži "sample": true;
uzorci povezani s pozivima koriste call_id: 0 i 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 prihvaća bilo koju vrijednost iz odjeljka Valjane vrste događaja.
Ako ga izostavite, zadržava se općenito ponašanje webhook.test.
Uzorci dovršetka poziva (telephony.complete, web.complete) i call.data_extracted
sadrže vlastita polja agenta za prikupljanje podataka u odjeljku
extracted_data.fields, s vrijednostima rezerviranih mjesta, kao i njegovi stvarni pozivi. Za
agenta koji ne prikuplja podatke uzorak dovršetka poziva šalje
extracted_data: null, kao i njegovi stvarni pozivi, a uzorak call.data_extracted
ima prazna fields (stvarni pozivi nikada ne šalju taj događaj za takvog agenta).
summary uzorka je null kada je sažetak poziva agenta isključen. Na krajnjoj točki
agenta uzorak slijedi tog agenta; na krajnjoj točki za cijelu organizaciju
proslijedite neobavezni agent_id kako biste ga oblikovali prema jednom agentu ili ga izostavite
za generički uzorak.
Izbrišite krajnju točku
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Vraća 204 No Content. Isporuka na URL odmah prestaje;
ponovni pokušaji u tijeku se napuštaju.
Otklanjanje pogrešaka isporuka
Prije nego što zaključite da webhook nije poslan, pregledajte
GET /v1/developer/webhook-deliveries.
Prikazuje nedavne pokušaje iz oba sustava webhookova, uključujući ID poziva,
izvor URL-a, HTTP status, broj pokušaja, kategoriju neuspjeha s popisa dopuštenih i vrijeme sljedećeg
ponovnog pokušaja. Nikada ne vraća sadržaj događaja, transkript, pohranjeni tekst pogreške,
tijelo odgovora ni putanju URL-a.
Istu nedavnu povijest možete vidjeti i u Agenti → odaberite agenta → Webhookovi → Nedavne isporuke. Retci prikazuju oznaku krajnje točke i izvor URL-a upotrijebljen u najnovijem pokušaju. Ovo je operativno stanje, a ne nepromjenjivi zapis revizije: brisanjem krajnje točke brišu se i njezini retci isporuke.
Za n8n 404 najprije potvrdite da je tijek rada aktivan, prihvaća POST i koristi
produkcijski URL webhooka umjesto testnog URL-a. 401 ili 403 ukazuje na
autentifikaciju ili provjeru potpisa; prekoračenja vremena ukazuju na latenciju
ili dostupnost odredišta; TLS pogreške ukazuju na lanac certifikata, naziv hosta ili istek.