Webhook-päätepisteet

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, 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

{
  "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). 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.

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

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

Palauttaa taulukon päätepisteobjekteja.

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

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; kaksoiskappaleet poistetaan

Palauttaa vastauksen 201 Created, joka sisältää päätepisteobjektin sekä ylimääräisen ylätason secret-kentän, joka sisältää raaka-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"
}

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

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.

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.

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 vastauksen 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, toimitus noudattaa samaa uudelleenyritysaikataulua kuin normaalit tapahtumatoimitukset.

Poista päätepiste

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ää

Tapahtumaluettelo

Täydellinen luettelo events-arvoista, joita voit tilata.

Webhookien yleiskatsaus

Allekirjoituksen vahvistus ja toimituksen semantiikka.

Webhooks

Function Tools

Päätepisteet

Päätepisteobjekti

Kelvolliset tapahtumatyypit

Päätepisteiden tilat

Listaa päätepisteet

Luo päätepiste

Pyynnön kentät

Päivitä päätepiste

Lähetä testitoimitus

Poista päätepiste

Aiheeseen liittyvää

Tapahtumaluettelo

Webhookien yleiskatsaus

​Päätepisteet

​Päätepisteobjekti

​Kelvolliset tapahtumatyypit

​Päätepisteiden tilat

​Listaa päätepisteet

​Luo päätepiste

​Pyynnön kentät

​Päivitä päätepiste

​Lähetä testitoimitus

​Poista päätepiste

​Aiheeseen liittyvää

Tapahtumaluettelo

Webhookien yleiskatsaus

Päätepisteet

Päätepisteobjekti

Kelvolliset tapahtumatyypit

Päätepisteiden tilat

Listaa päätepisteet

Luo päätepiste

Pyynnön kentät

Päivitä päätepiste

Lähetä testitoimitus

Poista päätepiste

Aiheeseen liittyvää