Webhook-päätepisteet

Hallitse useita webhook-URL-osoitteita päätepistekohtaisilla salaisuuksilla ja tapahtumasuodattimilla.

Päätepistepohjaisen webhook-järjestelmän avulla voit rekisteröidä useita kohteita organisaatiota kohti. Jokaisella on oma salaisuutensa, oma tilansa ja oma tilauksensa tapahtumatyyppien osajoukkoon. Tämä on suositeltu malli kaikille uusille integraatioille.

Vertaa tätä vanhaan yhden URL-osoitteen webhookiin, joka säilytetään taaksepäin yhteensopivuuden vuoksi mutta tukee vain yhtä URL-osoitetta organisaatiota kohti.

Päätepisteet#

Päätepisteobjekti#

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

Kelvolliset tapahtumatyypit#

events validoidaan täsmälleen tätä joukkoa vasten — luettelon ulkopuoliset arvot palauttavat virheen 400. Katso kunkin tyypin tietosisällön muoto kohdasta Tapahtumaluettelo.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (varattu; ei vielä lähetetä)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

Tapahtumalla issue.escalated ei ole agenttikontekstia, ja se toimitetaan vain organisaationlaajuisille päätepisteille.

Tapahtumia voice.ready ja voice.failed ei voi valita erikseen. Saat ne luomalla organisaationlaajuisen päätepisteen, jossa on events: []. Tyhjä tapahtumaluettelo vastaanottaa kaikki tuetut tapahtumat paitsi telephony.turn ja web.turn, jotka on valittava erikseen.

Päätepisteen tilat#

• active — toimitukset toimivat normaalisti.
• disabled — keskeytetty manuaalisesti PATCH-pyynnöllä. Pyyntöjä ei lähetetä. Emme koskaan muuta disabled-päätepisteen tilaa; sen muuttaminen takaisin active-tilaan on aina sinun päätöksesi.
• failing — asetetaan automaattisesti, kun toimitus päätepisteeseen käy läpi koko uudelleenyritysaikataulunsa (8 yritystä 24 tunnin aikana) saamatta koskaan 2xx-vastausta. Epäonnistuva päätepiste ei vastaanota enää liikennettä. Lähetämme tällöin sähköpostia organisaatiosi omistajille ja ylläpitäjille, ja hallintapaneelissa keskeytetyn päätepisteen kohdalla näkyy Aktivoi uudelleen -painike. Kun päätepiste on korjattu, muuta sen tila PATCH-pyynnöllä takaisin active-tilaan; toimitukset, joiden uudelleenyritysaikataulu ei ole vielä päättynyt, jatkuvat siitä, mihin ne jäivät.

Luettele päätepisteet#

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

Palauttaa taulukon päätepisteobjekteja. Välitä ?agent_id=42, jotta palautetaan vain tähän agenttiin rajatut päätepisteet.

Agenttikohtaiset päätepisteet#

Organisaationlaajuiset päätepisteet vastaanottavat kaikki vastaavat tapahtumat. Päätepiste, jolla on agent_id, vastaanottaa vain kyseisen agentin hoitamiin puheluihin liittyvät vastaavat tapahtumat; tapahtumat, joilla ei ole agenttikontekstia, kuten alert.triggered, eivät koskaan saavuta sitä. Voit myös luoda ja hallita näitä päätepisteitä agenttirakentajan Webhookit-osiosta.

Luo päätepiste#

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

Pyynnön kentät#

Palauttaa tilan 201 Created ja päätepisteobjektin sekä ylimääräisen ylimmän tason secret-kentän, joka sisältää raakan allekirjoitusavaimen — 48-merkkisen heksadesimaalimerkkijonon:

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

Päivitä päätepiste#

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

Palauttaa tilan 200 OK ja päivitetyn päätepisteobjektin.

Kierrätä allekirjoitussalaisuus#

Vaihda päätepisteen allekirjoitussalaisuus esimerkiksi silloin, kun se on kadonnut tai on voinut vuotaa. Agenttikohtaiselle päätepisteelle voit käyttää myös hallintapaneelia: avaa agentin Webhookit-osio ja valitse päätepisteelle Luo salaisuus uudelleen. Organisaationlaajuiset päätepisteet kierrätetään API:n kautta.

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

Palauttaa 200 OK:

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

Lähetä testitoimitus#

Lähetä synteettinen webhook.test-tapahtuma yhteen päätepisteeseen tavallista toimitusputkea käyttäen, mukaan lukien kanoninen JSON-sarjoitus, molemmat allekirjoitusotsakkeet, toimituksen tallennus ja uudelleenyritysten seuranta. Testi kohdistuu valittuun päätepisteeseen sen events-suodattimesta riippumatta.

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

Päätepiste vastaanottaa seuraavanlaisen kirjekuoren:

{
  "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 palauttaa 200 OK ensimmäisen yrityksen jälkeen, vaikka kohde palauttaisi virheen. Tarkista toimituksen tulos kentistä 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 synteettinen eikä sitä voi lisätä päätepisteen events-tilaukseen. Jos ensimmäinen yritys epäonnistuu, ThunderPhone yrittää sitä uudelleen kerran noin minuutin kuluttua ja lopettaa sitten; toimituksen tilana näkyy tällöin status: "failed" kohdassa Toimitusten vianmääritys. Testitoimitus ei koskaan merkitse päätepistettä failing-tilaan.

Jos haluat määrittää laukaisimen todellista tapahtumamuotoa vasten, välitä valinnainen event_type. Toimitus on edelleen synteettinen ja sisältää "sample": true; puheluihin liittyvissä esimerkeissä käytetään arvoja 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 hyväksyy minkä tahansa arvon kohdasta Kelvolliset tapahtumatyypit. Sen pois jättäminen säilyttää yleisen webhook.test-toiminnan.

Poista päätepiste#

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

Palauttaa 204 No Content. Toimitukset URL-osoitteeseen loppuvat välittömästi; käynnissä olevat uudelleenyritykset hylätään.

Toimitusten vianmääritys#

Ennen kuin päättelet, ettei webhookia lähetetty, tarkista GET /v1/developer/webhook-deliveries. Se näyttää molempien webhook-järjestelmien viimeisimmät yritykset, mukaan lukien puhelutunnuksen, URL-osoitteen alkuperän, HTTP-tilan, yritysten määrän, sallittujen virheiden luokan ja seuraavan uudelleenyrityksen ajan. Se ei koskaan palauta tapahtuman hyötykuormaa, transkriptiota, tallennettua virhetekstiä, vastauksen runkoa tai URL-polkuja.

Näet saman viimeisimmän historian myös kohdassa Agentit → valitse agentti → Webhookit → Viimeisimmät toimitukset. Riveillä näkyvät päätepisteen tunniste ja viimeisimmässä yrityksessä käytetty URL-osoitteen alkuperä. Kyseessä on toimintatila eikä muuttumaton tarkastusloki: päätepisteen poistaminen poistaa myös sen toimitusrivit.

Jos n8n palauttaa 404, varmista ensin, että työnkulku on aktiivinen, hyväksyy POST-pyynnöt ja käyttää tuotannon webhook-URL-osoitetta test-URL-osoitteen sijaan. 401 tai 403 viittaa todennukseen tai allekirjoituksen validointiin; aikakatkaisut viittaavat kohteen viiveeseen tai saatavuuteen; TLS-virheet viittaavat varmenneketjuun, isäntänimeen tai vanhenemiseen.

Aiheeseen liittyvää#