Webhooki lõpp-punktid

Halda mitut webhooki URL-i iga lõpp-punkti saladuste ja sündmusefiltritega.

Lõpp-punktidel põhinev webhook-süsteem võimaldab registreerida organisatsiooni kohta mitu sihtkohta, millest igaühel on oma saladus, olek ja tellimus teatud sündmusetüüpide alamhulgale. See on soovitatud mudel kõigi uute integratsioonide jaoks.

Võrdle pärand ühe URL-iga webhookiga, mida säilitatakse tagasiühilduvuse tagamiseks, kuid mis toetab organisatsiooni kohta ainult üht URL-i.

Lõpp-punktid#

Endpointi objekt#

{
  "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"
}

Kehtivad sündmuste tüübid#

events valideeritakse täpselt selle loendi alusel — loendivälised väärtused tagastavad 400. Iga tüübi kasuliku koorma vormingu leiad sündmuste kataloogist.

• 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 ei sisalda agendi konteksti ja edastatakse ainult kogu organisatsiooni hõlmavatele endpointidele.

voice.ready ja voice.failed ei ole selgesõnaliselt valitavad. Nende vastuvõtmiseks loo kogu organisatsiooni hõlmav endpoint väärtusega events: []. Tühi sündmuste loend võtab vastu kõik toetatud sündmused, välja arvatud telephony.turn ja web.turn, mis tuleb valida selgesõnaliselt.

Endpointi olekud#

• active — edastused toimivad tavapäraselt.
• disabled — käsitsi peatatud PATCH-iga. Taotlusi ei saadeta. Me ei muuda kunagi disabled endpointi olekut; selle tagasi active-ks muutmine on alati sinu otsus.
• failing — määratakse automaatselt, kui endpointile suunatud edastus kasutab ära kogu korduskatsete ajakava (8 katset 24 tunni jooksul), saamata kordagi 2xx vastust. Tõrkuv endpoint ei saa edasist liiklust. Kui endpoint on parandatud, muuda selle olek PATCH-iga tagasi väärtuseks active; edastused, mille korduskatsete ajakava pole veel lõppenud, jätkuvad sealt, kus need pooleli jäid.

Endpointide loetlemine#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Tagastab massiivi endpointi objektidest. Ainult selle agendiga seotud endpointide tagastamiseks edasta ?agent_id=42.

Agendiga seotud endpointid#

Kogu organisatsiooni hõlmavad endpointid võtavad vastu kõik sobivad sündmused. Endpoint väärtusega agent_id võtab vastu ainult selle agendi hallatud kõnedega seotud sobivad sündmused; agendi kontekstita sündmused, näiteks alert.triggered, ei jõua selleni kunagi. Neid endpointe saad luua ja hallata ka agendi koostaja jaotises Veebikonksud.

Loo lõpp-punkt#

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"]

Päringu väljad#

Tagastab 201 Created koos lõpp-punkti objektiga ning täiendava tipptaseme väljaga secret, mis sisaldab toorest allkirjastamisvõtit — 48-märgilist kuueteistkümnendsüsteemi stringi:

{
  "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"
}

Uuenda lõpp-punkti#

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

Tagastab 200 OK koos uuendatud lõpp-punkti objektiga.

Saada testtarne#

Saada sünteetiline webhook.test sündmus ühele lõpp-punktile tavapärase tarnekonveieri kaudu, sealhulgas kanooniline JSON-i serialiseerimine, X-ThunderPhone-Signature, tarne salvestamine ja korduskatsete arvestus. Test sihib valitud lõpp-punkti sõltumata selle events filtrist.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Lõpp-punkt saab järgmise ümbriku:

{
  "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 tagastab 200 OK pärast esimest katset isegi siis, kui sihtkoht tagastab vea. Tarne tulemi vaatamiseks kontrolli success, status, response_code ja error väärtusi:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test on sünteetiline ja seda ei saa lisada lõpp-punkti events tellimusse. Kui esimene katse ebaõnnestub, järgib tarne sama korduskatsete ajakava nagu tavalised sündmuste tarned.

Päästiku seadistamiseks tegeliku sündmuse kuju alusel edasta valikuline event_type. Tarne on endiselt sünteetiline ja sisaldab "sample": true; kõnega seotud näidised kasutavad väärtusi call_id: 0 ja 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 aktsepteerib mis tahes väärtust loendist Kehtivad sündmuste tüübid. Selle väljajätmine säilitab üldise webhook.test käitumise.

Kustuta lõpp-punkt#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Tagastab 204 No Content. URL-ile tarnimine peatub kohe; pooleliolevatest korduskatsetest loobutakse.

Silu tarneid#

Enne kui järeldad, et veebikonksu ei saadetud, kontrolli GET /v1/developer/webhook-deliveries. See näitab mõlema veebikonksusüsteemi hiljutisi katseid, sealhulgas kõne ID-d, URL-i päritolu, HTTP olekut, katsete arvu, lubatud loendisse lisatud tõrkekategooriat ja järgmist korduskatse aega. See ei tagasta kunagi sündmuse koormust, transkriptsiooni, salvestatud veateksti, vastuse sisu ega URL-i teed.

Sama hiljutist ajalugu näed ka jaotises Agendid → vali agent → Veebikonksud → Hiljutised tarned. Ridadel kuvatakse lõpp-punkti silt ja uusima katse kasutatud URL-i päritolu. See on tegevuslik olek, mitte muutumatu auditilogi: lõpp-punkti kustutamine kustutab ka selle tarneridad.

n8n-i 404 vea korral kontrolli esmalt, et töövoog on aktiivne, aktsepteerib POST päringuid ja kasutab tootmise veebikonksu URL-i, mitte testi-URL-i. 401 või 403 viitab autentimisele või allkirja valideerimisele; ajalõpud viitavad sihtkoha latentsusele või saadavusele; TLS-i vead viitavad sertifikaadiahelale, hostinimele või aegumisele.

Seotud#