Webhooks

Webhook-päätepisteet

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

Päätepistepohjaisen webhook-järjestelmän avulla voit rekisteröidä organisaatiota kohden useita kohteita, joilla kullakin 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 on säilytetty taaksepäin yhteensopivuuden vuoksi mutta tukee vain yhtä URL-osoitetta organisaatiota kohden.

Päätepisteet#

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

Kelvolliset tapahtumatyypit#

events validoidaan täsmälleen tätä joukkoa vasten — luettelon ulkopuoliset arvot palauttavat 400. Katso kunkin tyypin hyötykuorman rakenne tapahtumaluettelosta.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• 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; palauttaminen takaisin tilaan active on aina sinun päätöksesi.
• failing — asetetaan automaattisesti, kun toimitus päätepisteeseen käyttää koko uudelleenyritysaikataulunsa (8 yritystä 24 tunnin aikana) saamatta yhtäkään 2xx-vastausta. Epäonnistuva päätepiste ei vastaanota enää liikennettä. Kun päätepiste on korjattu, PATCH-pyynnöllä sen tila 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#

Palauttaa vastauksen 201 Created, joka sisältää päivitetyn päätepisteobjektin sekä ylimääräisen ylätason secret-kentän, joka sisältää raa'an 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 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, mukaan lukien kanoninen JSON-sarjoitus, X-ThunderPhone-Signature, 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, 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 204 No Content. Toimitus URL-osoitteeseen lakkaa välittömästi; käynnissä olevat uudelleenyritykset keskeytetään.

Aiheeseen liittyvää#