> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 kohden. Jokaisella on oma salaisuutensa, oma tilansa ja oma tilauksensa tapahtumatyyppien osajoukkoon. Tämä on suositeltu malli kaikille uusille integraatioille. Vertaa [vanhaan yhden URL-osoitteen webhookiin](/api-reference/organizations#legacy-single-url-webhook), joka säilytetään taaksepäin yhteensopivuuden vuoksi, mutta joka tukee vain yhtä URL-osoitetta organisaatiota kohden. ## Päätepisteet | Metodi | 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-osoite / tapahtumat / tila | | `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Poista päätepiste | | `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Lähetä allekirjoitettu testitoimitus | ## Päätepisteobjekti ```json theme={null} { "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" } ``` | Kenttä | Tyyppi | Kuvaus | | -------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | UUID | Päätepisteen tunniste | | `label` | string | Näyttönimi, 1–120 merkkiä | | `url` | string | HTTPS-URL-osoite; `http://localhost` sallitaan kehityksessä | | `events` | merkkijonotaulukko | Tilatut tapahtumatyypit (katso [kelvolliset arvot](#valid-event-types)). Tyhjä taulukko tilaa kaikki tapahtumat | | `status` | string | `active`, `disabled` (manuaalisesti keskeytetty) tai `failing` (asetetaan automaattisesti, kun toimituksen 24 tunnin uudelleenyritysaikataulu päättyy ilman yhtäkään 2xx-vastausta) | | `secret_hint` | string | Allekirjoitussalaisuuden ensimmäiset 4 ja viimeiset 4 merkkiä sekä ellipsi (`a1b2…9f0e`) — riittää paikallisesti tallentamasi salaisuuden tunnistamiseen paljastamatta koko arvoa | | `created_at`, `updated_at` | aikaleima | | Päätepisteen täydellinen `secret` palautetaan **vain kerran** luomisen yhteydessä, eikä enää koskaan. Tallenna se turvallisesti — jos kadotat sen, poista päätepiste ja luo se uudelleen. ### Kelvolliset tapahtumatyypit `events` validoidaan täsmälleen tätä joukkoa vasten — luettelon ulkopuoliset arvot palauttavat `400`-vastauksen. Katso kunkin tyypin hyötykuorman muoto [tapahtumaluettelosta](/fi/webhooks/events). * `telephony.incoming`, `telephony.complete`, `telephony.tool` * `web.incoming`, `web.complete`, `web.tool` * `call.graded` * `issue.reported` * `test-call.completed` * `alert.triggered` ### Päätepisteiden tilat * `active` — toimitukset kulkevat normaalisti. * `disabled` — keskeytetty manuaalisesti `PATCH`-pyynnöllä. Pyyntöjä ei lähetetä. Emme koskaan muuta `disabled`-päätepisteen tilaa; sen vaihtaminen takaisin tilaan `active` on aina sinun päätöksesi. * `failing` — asetetaan automaattisesti, kun päätepisteeseen tehtävä toimitus käyttää koko uudelleenyritysaikataulunsa (8 yritystä 24 tunnin aikana) saamatta koskaan 2xx-vastausta. Epäonnistuva päätepiste ei vastaanota enää liikennettä. Kun päätepiste on korjattu, muuta sen tila `PATCH`-pyynnöllä takaisin tilaan `active`; toimitukset, joiden uudelleenyritysaikataulu ei ole vielä päättynyt, jatkuvat siitä, mihin ne jäivät. *** ## Listaa päätepisteet ```bash cURL theme={null} curl https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Palauttaa taulukon [päätepisteobjekteja](#endpoint-object). *** ## Luo päätepiste ```bash cURL theme={null} 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 theme={null} 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-osoite (`http` sallitaan vain kohteille `localhost` / `127.0.0.1`) | | `events` | taulukko | ei | Tyhjä tai puuttuva arvo tilaa kaikki tapahtumat. Käytä arvoja, jotka on lueteltu kohdassa [Kelvolliset tapahtumatyypit](#valid-event-types); kaksoiskappaleet poistetaan | Palauttaa vastauksen `201 Created`, joka sisältää [päätepisteobjektin](#endpoint-object) sekä ylimääräisen ylätason `secret`-kentän, joka sisältää raaka-allekirjoitusavaimen — 48-merkkisen heksadesimaalimerkkijonon: ```json theme={null} { "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 kentän `secret_hint`. Kopioi koko arvo salaisuuksien hallintaan ennen kuin suljet vastauksen. *** ## Päivitä päätepiste ```bash cURL theme={null} 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`, jos haluat ottaa uudelleen käyttöön päätepisteen, jonka palvelin on merkinnyt tilaan `failing` | Palauttaa vastauksen `200 OK`, joka sisältää päivitetyn [päätepisteobjektin](#endpoint-object). *** ## Lähetä testitoimitus Lähetä synteettinen `webhook.test`-tapahtuma yhteen päätepisteeseen normaalin toimitusputken kautta. Se sisältää kanonisen JSON-sarjoituksen, `X-ThunderPhone-Signature`-allekirjoituksen, toimituksen tallennuksen ja uudelleenyritysten seurannan. Testi kohdistuu valittuun päätepisteeseen sen `events`-suodattimesta riippumatta. ```bash cURL theme={null} 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 theme={null} { "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 vastauksen `200 OK` ensimmäisen yrityksen jälkeen, vaikka kohde palauttaisi virheen. Tarkista toimituksen tulos kentistä `success`, `status`, `response_code` ja `error`: ```json theme={null} { "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, toimitus noudattaa samaa uudelleenyritysaikataulua kuin normaalit tapahtumatoimitukset. *** ## Poista päätepiste ```bash cURL theme={null} curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Palauttaa arvon `204 No Content`. Toimitus URL-osoitteeseen päättyy välittömästi; käynnissä olevat uudelleenyritykset keskeytetään. *** ## Aiheeseen liittyvää Täydellinen luettelo `events`-arvoista, joita voit tilata. Allekirjoituksen vahvistus ja toimituksen semantiikka.