ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Webhooks

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

MetodaPutanjaPotrebna ulogaOpis
GET/v1/developer/webhook-endpointsadmin+Prikažite krajnje točke
POST/v1/developer/webhook-endpointsadmin+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-secretadmin+Zamijenite tajnu za potpisivanje
POST/v1/developer/webhook-endpoints/{endpoint_id}/testadmin+Pošaljite potpisanu probnu isporuku
GET/v1/developer/webhook-deliveriesadmin+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"
}
PoljeVrstaOpis
idUUIDID krajnje točke
labelstringPrikazni naziv, 1–120 znakova
urlstringHTTPS URL; http://localhost dopušten za razvoj
eventsniz stringovaVrste 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)
statusstringactive, disabled (ručno pauzirano) ili failing (automatski postavljeno kada isporuka iscrpi raspored ponovnih pokušaja od 24 h bez ijednog odgovora 2xx)
agent_idinteger | nullAgent za kojeg je ova krajnja točka ograničena; null znači za cijelu organizaciju
agent_namestring | nullNaziv obuhvaćenog agenta ili null za krajnju točku na razini organizacije
secret_hintstringPrva 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_attimestamp | nullKada je ThunderPhone postavio krajnju točku na failing. null dok je active ili disabled
pause_last_errorstringPosljednja pogreška isporuke kada je krajnja točka pauzirana, na primjer HTTP 503: Service Unavailable. Prazno osim ako je failing
pause_undelivered_countinteger | nullDogađaji koji nisu isporučeni od posljednje uspješne isporuke krajnje točke, izbrojeni kada je pauzirana
created_at, updated_attimestamp

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.turn
  • web.incoming, web.complete, web.tool, web.turn
  • sms.sent, sms.failed
  • sms.received (rezervirano; još se ne šalje)
  • scheduled.skipped, scheduled.failed
  • call.graded, call.data_extracted, call.transfer_completed, call.status_changed
  • campaign.completed
  • issue.reported, issue.escalated
  • test-call.completed
  • alert.triggered
  • phone_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 putem PATCH. Zahtjevi se ne šalju. Nikada ne mijenjamo status krajnje točke disabled; vraćanje na active uvijek 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 putem PATCH vratite na active; isporuke čiji raspored ponovnih pokušaja još nije istekao nastavljaju tamo gdje su stale.

Popis krajnjih točaka

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

PoljeVrstaObaveznoOpis
labelniz znakovada1–120 znakova
urlniz znakovadaHTTPS URL (http je dopušten samo za localhost / 127.0.0.1)
eventsniznePrazno/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_idcijeli broj | nullneOgranič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
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"]
  }'
PoljeVrstaOpis
labelniz znakova
urlniz znakova
eventspolje
statusniz znakovaactive ili disabled. Postavite active da biste ponovno omogućili krajnju točku koju je poslužitelj označio kao failing
agent_idcijeli broj | nullPostavite 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
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 '{}'
PoljeVrstaObaveznoOpis
include_copiesbooleanneZadano 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-..."]
}
PoljeVrstaOpis
endpointobjectObjekt krajnje točke s novim secret_hint
secretstringNova tajna za potpisivanje. Vraća se samo u ovom odgovoru
rotated_endpoint_idspolje UUID-ovaSvaka 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
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
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.


Povezano