ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Webhooks

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

MetodaPotZahtevana vlogaOpis
GET/v1/developer/webhook-endpointsadmin+Prikažite končne točke
POST/v1/developer/webhook-endpointsadmin+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-secretadmin+Zamenjajte skrivnost za podpisovanje
POST/v1/developer/webhook-endpoints/{endpoint_id}/testadmin+Pošljite podpisano testno dostavo
GET/v1/developer/webhook-deliveriesadmin+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"
}
PoljeVrstaOpis
idUUIDID končne točke
labelnizPrikazno ime, 1–120 znakov
urlnizURL HTTPS; http://localhost je dovoljen za razvoj
eventspolje nizovVrste 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)
statusnizactive, disabled (ročno zaustavljeno) ali failing (samodejno nastavljeno, ko dostava porabi 24-urni urnik ponovnih poskusov brez enega samega odgovora 2xx)
agent_idcelo število | nullAgent, na katerega je omejena ta končna točka; null pomeni za celotno organizacijo
agent_nameniz | nullIme omejenega agenta ali null za končno točko za celotno organizacijo
secret_hintnizPrvi 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_errornizZadnja napaka dostave, ko je bila končna točka zaustavljena, na primer HTTP 503: Service Unavailable. Prazno, razen če je failing
pause_undelivered_countcelo število | nullDogodki, 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.turn
  • web.incoming, web.complete, web.tool, web.turn
  • sms.sent, sms.failed
  • sms.received (rezervirano; še ni poslano)
  • 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 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 prek PATCH. Zahteve se ne pošiljajo. Stanja končne točke disabled nikoli ne spremenimo; odločitev o ponovni spremembi v active je 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, z PATCH njeno stanje spremenite nazaj v active; dostave, katerih razpored ponovnih poskusov še ni potekel, se nadaljujejo tam, kjer so se ustavile.

Seznam končnih točk

cURL
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
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 zahteve

PoljeVrstaObveznoOpis
labelnizda1–120 znakov
urlnizdaURL HTTPS (http je dovoljen samo za localhost / 127.0.0.1)
eventspoljenePrazno/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_idcelo število | nullneOmejite 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
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
urlniz
eventspolje
statusnizactive ali disabled. Nastavite active, da znova omogočite končno točko, ki jo je strežnik označil kot failing
agent_idcelo število | nullNastavite 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
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 '{}'
PoljeVrstaObveznoOpis
include_copieslogična vrednostnePrivzeto 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-..."]
}
PoljeVrstaOpis
endpointobjektObjekt končne točke z novim secret_hint
secretnizNova podpisna skrivnost. Vrne se samo v tem odgovoru
rotated_endpoint_idspolje UUID-jevVsaka 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
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
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.


Povezano