Webhooki lõpp-punktid

Halda mitut webhooki URL-i lõpp-punktipõhiste saladuste ja sündmusefiltritega.

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

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

Lõpp-punktid#

Lõpp-punkti 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",
  "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"
}

Kehtivad sündmuste tüübid#

events kontrollitakse täpselt selle loendi alusel — loendiväliste väärtuste korral tagastatakse 400. Iga tüübi andmekoormuse vormingu kohta vaata Sündmuste kataloogi.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (reserveeritud; veel ei edastata)
• scheduled.skipped, scheduled.failed
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered
• phone_number.spam_risk_changed

issue.escalated ja phone_number.spam_risk_changed ei sisalda agendi konteksti ning edastatakse ainult organisatsiooniülestele lõpp-punktidele.

voice.ready ja voice.failed ei ole selgesõnaliselt valitavad. Nende vastuvõtmiseks loo organisatsiooniülene lõpp-punkt 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 selgesõnaliselt valida.

Lõpp-punkti olekud#

• active — edastused toimivad tavapäraselt.
• disabled — käsitsi PATCH-iga peatatud. Ühtegi päringut ei saadeta. Me ei muuda kunagi disabled-olekus lõpp-punkti olekut; selle tagasi active-olekusse muutmine on alati sinu otsus.
• failing — määratakse automaatselt, kui edastus lõpp-punkti kasutab kogu korduskatsete ajakava (8 katset 24 tunni jooksul), saamata kordagi 2xx-vastust. Tõrkuv lõpp-punkt ei saa rohkem liiklust. Kui see juhtub, saadame e-kirja sinu organisatsiooni omanikele ja administraatoritele ning juhtpaneelil kuvatakse peatatud lõpp-punkt nupuga Taasaktiveeri. Kui lõpp-punkt on parandatud, muuda selle olek PATCH-iga tagasi active-ks; edastused, mille korduskatsete ajakava pole veel lõppenud, jätkuvad sealt, kus need pooleli jäid.

Lõpp-punktide loetlemine#

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

Tagastab massiivi lõpp-punkti objekte. Ainult sellele häälagendile piiratud lõpp-punktide tagastamiseks kasuta ?agent_id=42.

Häälagendile piiratud lõpp-punktid#

Organisatsiooniülesed lõpp-punktid saavad kõik sobivad sündmused. Lõpp-punkt väärtusega agent_id saab ainult selle häälagendi hallatud kõnede sobivad sündmused; häälagendi kontekstita sündmused, näiteks alert.triggered, ei jõua selleni kunagi. Neid lõpp-punkte saad luua ja hallata ka häälagendi 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.

Vaheta allkirjastamise saladus#

Asenda lõpp-punkti allkirjastamise saladus, näiteks kui see kadus või võis lekkida. Agendipõhise lõpp-punkti jaoks saad kasutada ka juhtpaneeli: ava agendi jaotis Veebikonksud ning vali lõpp-punktis Loo saladus uuesti. Organisatsiooniüleseid lõpp-punkte vahetatakse API kaudu.

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

Tagastab 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Saada testiedastus#

Saada sünteetiline webhook.test sündmus ühte lõpp-punkti tavapärase edastustorustiku kaudu, sealhulgas kanoonilise JSON-i serialiseerimise, mõlema allkirjapäise, edastuse salvestamise ja korduskatsete arvestusega.
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 ümbrise:

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

{
  "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 tellimusele. Kui esimene katse ebaõnnestub, proovib ThunderPhone seda umbes minut hiljem veel üks kord ja siis peatub; edastuse olekuks kuvatakse status: "failed" jaotises Edastuste silumine. Testiedastus ei märgi lõpp-punkti kunagi failing olekusse.

Käiviti seadistamiseks tegeliku sündmuse struktuuri järgi edasta valikuline event_type. Edastus on endiselt sünteetiline ja sisaldab väärtust "sample": true; kõnedega seotud näidised kasutavad 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ündmusetüübid. Selle väljajätmisel säilib üldine webhook.test käitumine.

Kõne lõpetamise (telephony.complete, web.complete) ja call.data_extracted näidised sisaldavad agendi enda kogutavaid andmevälju jaotises extracted_data.fields, kohatäiteväärtustega, nagu ka agendi tegelikud kõned. Agendi puhul, kes andmeid ei kogu, saadab kõne lõpetamise näidis extracted_data: null, nagu ka selle agendi tegelikud kõned, ning call.data_extracted näidisel on tühjad fields-väljad (tegelikud kõned ei saada sellise agendi puhul seda sündmust). Näidise summary on null, kui agendi kõne kokkuvõte on välja lülitatud. Agendi lõpp-punktis järgib näidis seda agenti; kogu organisatsiooni hõlmavas lõpp-punktis anna näidise kujundamiseks ühe agendi järgi valikuline agent_id või jäta see üldise näidise jaoks välja.

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 edastamine peatub kohe; pooleliolevad korduskatsed katkestatakse.

Edastuste silumine#

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 kantud tõrkekategooriat ja järgmist korduskatse aega. See ei tagasta kunagi sündmuse andmekoormust, transkriptsiooni, salvestatud veateksti, vastuse sisu ega URL-i teed.

Sama hiljutist ajalugu näed ka menüüs Agendid → vali agent → Veebikonksud → Hiljutised edastused. Ridadel kuvatakse lõpp-punkti silt ja viimase katse kasutatud URL-i päritolu. See on tööolek, mitte muutumatu auditilogi: lõpp-punkti kustutamine kustutab ka selle edastusridad.

n8n 404 korral kontrolli esmalt, et töövoog on aktiivne, aktsepteerib POST päringuid ja kasutab test-URL-i asemel tootmise veebikonksu URL-i. 401 või 403 osutab autentimise või allkirja valideerimise probleemile; ajalõpud osutavad sihtkoha latentsusele või kättesaadavusele; TLS-i vead osutavad sertifikaadiahelale, hostinimele või aegumisele.

Seotud#