Končne točke webhookov

Upravljajte več URL-jev webhookov s skrivnostmi in filtri dogodkov za posamezne končne točke.

Sistem webhookov, ki temelji na končnih točkah, vam omogoča registracijo več ciljev za posamezno organizacijo, pri čemer ima vsak svojo skrivnost, svoje stanje in svojo naročnino na podmnožico vrst dogodkov. To je priporočeni model za vse nove integracije.

Primerjajte 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#

Predmet 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",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Veljavne vrste dogodkov#

events se preverja glede na ta natančen 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
• call.graded, call.data_extracted
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated nima konteksta agenta in se dostavi samo končnim točkam za celotno organizacijo.

voice.ready in voice.failed ni mogoče izbrati izrecno. Če ju želite prejemati, ustvarite končno točko za celotno organizacijo z events: []. Prazen seznam dogodkov prejme vsak podprti dogodek razen telephony.turn in web.turn, ki ju 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 spreminjamo; ali jo boste znova nastavili na active, je vedno vaša odločitev.
• failing — samodejno nastavljeno, ko dostava na končno točko izčrpa celoten urnik 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 končno točko popravite, z PATCH njeno stanje znova nastavite na active; dostave, katerih urnik 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 predmetov končne točke. Dodajte ?agent_id=42, če želite vrniti samo končne točke, omejene na tega agenta.

Končne točke, omejene na agenta#

Končne točke za celotno organizacijo prejemajo vse ujemajoče se dogodke. 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 Spletne kljuke graditelja agenta.

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#

Vrne 201 Created s posodobljenim objektom končne točke in dodatnim poljem secret na najvišji ravni, ki vsebuje neobdelani podpisni ključ — 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"]
  }'

Vrne 200 OK s posodobljenim objektom končne točke.

Pošljite preskusno dostavo#

Pošljite sintetični dogodek webhook.test eni končni točki prek običajnega poteka dostave, vključno s kanonično serializacijo JSON, X-ThunderPhone-Signature, beleženjem dostave in evidenco 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 v naročnino events končne točke. Če prvi poskus ne uspe, dostava sledi enakemu urniku ponovnih poskusov kot običajne dostave dogodkov.

Če želite konfigurirati sprožilec za dejansko obliko 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 razdelka Veljavne vrste dogodkov. Če ga izpustite, se ohrani splošno vedenje webhook.test.

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 težav z dostavami#

Preden ugotovite, da webhook ni bil poslan, preglejte 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 s seznama dovoljenih in časom naslednjega ponovnega poskusa. Nikoli ne vrne podatkovnega dela dogodka, prepisa, shranjenega besedila napake, telesa odgovora ali poti URL-ja.

Enako nedavno zgodovino lahko vidite tudi v Agenti → izberite agenta → Webhooki → Nedavne dostave. Vrstice prikazujejo oznako končne točke in izvor URL-ja, uporabljen pri zadnjem poskusu. To je operativno stanje in ne nespremenljiv revizijski dnevnik: če izbrišete končno točko, se izbrišejo tudi njene vrstice dostav.

Pri napaki n8n 404 najprej potrdite, da je delovni tok aktiven, sprejema POST in uporablja produkcijski URL webhooka namesto preskusnega URL-ja. Napaka 401 ali 403 kaže na preverjanje pristnosti ali preverjanje podpisa; časovne omejitve kažejo na zakasnitev ali razpoložljivost cilja; napake TLS kažejo na verigo potrdil, ime gostitelja ali potek veljavnosti.

Povezano#