--- title: "Webhook-päätepisteet" description: "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](/api-reference/organizations#legacy-single-url-webhook), joka säilytetään taaksepäin yhteensopivuuden vuoksi mutta tukee vain yhtä URL-osoitetta organisaatiota kohti. ## Päätepisteet | Menetelmä | Polku | Vaadittu rooli | Kuvaus | |--------|------|---------------|-------------| | `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Listaa päätepisteet | | `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Luo päätepisteen | | `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Päivitä tunniste / URL / tapahtumat / tila | | `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Poista päätepiste | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Korvaa allekirjoitussalaisuus | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Lähetä allekirjoitettu testitoimitus | | `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Tarkastele viimeisimpiä päätepisteiden ja vanhojen toimitusten tuloksia | ## Päätepisteobjekti ```json { "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" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `id` | UUID | Päätepisteen tunnus | | `label` | string | Näyttönimi, 1–120 merkkiä | | `url` | string | HTTPS-URL-osoite; `http://localhost` sallitaan kehityksessä | | `events` | array of string | Tilattujen tapahtumien tyypit (katso [kelvolliset arvot](#valid-event-types)). Tyhjä taulukko tilaa kaikki tapahtumat lukuun ottamatta vain erikseen tilattavia vuorokohtaisia tapahtumia (`telephony.turn` / `web.turn`) | | `status` | string | `active`, `disabled` (manuaalisesti keskeytetty) tai `failing` (asetetaan automaattisesti, kun toimitus käyttää loppuun 24 tunnin uudelleenyritysaikataulunsa ilman yhtäkään 2xx-vastausta) | | `agent_id` | integer \| null | Agentti, johon tämä päätepiste on rajattu; `null` tarkoittaa organisaationlaajuista | | `agent_name` | string \| null | Rajatun agentin nimi tai `null` organisaationlaajuiselle päätepisteelle | | `secret_hint` | string | Allekirjoitussalaisuuden ensimmäiset 4 ja viimeiset 4 merkkiä sekä ellipsi (`a1b2…9f0e`) — riittää paikallisesti tallentamasi salaisuuden ristiinviittaukseen paljastamatta koko arvoa | | `paused_at` | timestamp \| null | Milloin ThunderPhone asetti päätepisteen tilaan `failing`. `null`, kun tila on `active` tai `disabled` | | `pause_last_error` | string | Viimeisin toimitusvirhe, kun päätepiste keskeytettiin, esimerkiksi `HTTP 503: Service Unavailable`. Tyhjä, ellei tila ole `failing` | | `pause_undelivered_count` | integer \| null | Tapahtumat, joita ei toimitettu päätepisteen viimeisen onnistuneen toimituksen jälkeen ja jotka laskettiin, kun se keskeytettiin | | `created_at`, `updated_at` | timestamp | | Päätepisteen koko `secret` palautetaan luonnin yhteydessä **vain kerran**, eikä sitä palauteta enää koskaan. Säilytä se turvallisesti — jos kadotat sen, [kierrätä se](#rotate-the-signing-secret) saadaksesi uuden. ### 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](/fi/webhooks/events). - `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 ```bash cURL curl https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Palauttaa taulukon [päätepisteobjekteja](#endpoint-object). 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 ```bash 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 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"] ``` ### Pyynnön kentät | Kenttä | Tyyppi | Pakollinen | Kuvaus | |-------|------|----------|-------------| | `label` | merkkijono | kyllä | 1–120 merkkiä | | `url` | merkkijono | kyllä | HTTPS-URL (`http` sallitaan vain kohteille `localhost` / `127.0.0.1`) | | `events` | taulukko | ei | Tyhjä tai pois jätetty arvo tilaa kaikki tapahtumat lukuun ottamatta `telephony.turn`- ja `web.turn`-tapahtumia, jotka edellyttävät nimenomaista tilausta. Käytä [kelvollisissa tapahtumatyypeissä](#valid-event-types) lueteltuja arvoja; kaksoiskappaleet poistetaan | | `agent_id` | kokonaisluku \| null | ei | Rajaa toimitus tämän organisaation agenttiin; jätä pois tai käytä arvoa `null` organisaation kattavaa päätepistettä varten | Palauttaa tilan `201 Created` ja [päätepisteobjektin](#endpoint-object) sekä ylimääräisen ylimmän tason `secret`-kentän, joka sisältää raakan allekirjoitusavaimen — 48-merkkisen heksadesimaalimerkkijonon: ```json { "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" } ``` `secret` palautetaan **vain luotaessa**. Myöhemmät `GET`-vastaukset sisältävät vain arvon `secret_hint`. Kopioi koko arvo salaisuuksien hallintajärjestelmääsi ennen kuin suljet vastauksen. --- ## Päivitä päätepiste ```bash 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"] }' ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `label` | merkkijono | | | `url` | merkkijono | | | `events` | taulukko | | | `status` | merkkijono | `active` tai `disabled`. Aseta arvoksi `active`, jotta voit ottaa uudelleen käyttöön päätepisteen, jonka palvelin on merkinnyt tilaan `failing` | | `agent_id` | kokonaisluku \| null | Aseta agenttitunnus rajataksesi päätepisteen tai `null`, jotta se kattaa koko organisaation | Palauttaa tilan `200 OK` ja päivitetyn [päätepisteobjektin](#endpoint-object). --- ## 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. ```bash 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 '{}' ``` | Kenttä | Tyyppi | Pakollinen | Kuvaus | |-------|------|----------|-------------| | `include_copies` | boolean | ei | Oletusarvo on `true`. Antaa uuden salaisuuden myös organisaatiosi muille päätepisteille, joilla on sama URL-osoite ja sama nykyinen salaisuus, kuten tämän päätepisteen kopioille muissa agenteissa, jotta yksi vastaanotin voi jatkaa tarkistamista yhdellä salaisuudella | Palauttaa `200 OK`: ```json { "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." }, "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d", "rotated_endpoint_ids": ["c4d5e6f7-..."] } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `endpoint` | object | [Päätepisteobjekti](#endpoint-object), jossa on uusi `secret_hint` | | `secret` | string | Uusi allekirjoitussalaisuus. Palautetaan vain tässä vastauksessa | | `rotated_endpoint_ids` | UUID-taulukko | Jokainen päätepiste, joka käyttää nyt uutta salaisuutta | Vanhan salaisuuden käyttö lakkaa välittömästi: seuraava toimitus, uudelleenyritykset mukaan lukien, allekirjoitetaan uudella salaisuudella. Kunnes vastaanottimellasi on uusi salaisuus, toimitukset eivät läpäise sen allekirjoituksen tarkistusta; jos se vastaa niihin muulla kuin 2xx-tilalla, niitä yritetään uudelleen normaalin 24 h:n aikataulun mukaisesti, joten päivitä vastaanotin viipymättä. Jos vastaanottimesi otetaan käyttöön vaiheittain, varmista, että se hyväksyy molemmat salaisuudet käyttöönoton aikana — SDK:n tarkistusapuohjelmat hyväksyvät salaisuuksien luettelon (katso [Tarkista webhook-allekirjoitukset](/fi/guides/verify-webhook-signatures)). --- ## 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. ```bash cURL 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: ```json { "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`: ```json { "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](#debug-deliveries). 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`. ```bash 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](#valid-event-types). Sen pois jättäminen säilyttää yleisen `webhook.test`-toiminnan. --- ## Poista päätepiste ```bash cURL 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`](/api-reference/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ää Täydellinen luettelo `events`-arvoista, joihin voit tilata ilmoituksia. Allekirjoituksen vahvistus ja toimitussemantiikka.