Webhooks

Tīmekļa aizķeru galapunkti

Pārvaldiet vairākus tīmekļa aizķeru URL ar katra galapunkta slepenajiem kodiem un notikumu filtriem.

Galapunktos balstītā tīmekļa aizķeru sistēma ļauj reģistrēt vairākus galamērķus katrai organizācijai, katram ar savu noslēpumu, savu statusu un abonementu notikumu tipu apakškopai. Šis ir ieteicamais modelis visām jaunajām integrācijām.

Salīdziniet ar mantoto vienas URL tīmekļa aizķeri, kas tiek uzturēta atpakaļsaderībai, bet katrai organizācijai atbalsta tikai vienu URL.

Galapunkti#

Galapunkta objekts#

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

Derīgie notikumu tipi#

events tiek validēts pret šo precīzo kopu — vērtības ārpus saraksta atgriež 400. Katram tipam pieejamo slodzes struktūru skatiet notikumu katalogā.

• 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

Galapunktu statusi#

• active — piegādes notiek normāli.
• disabled — manuāli apturēts, izmantojot PATCH. Pieprasījumi netiek sūtīti. Mēs nekad nemainām disabled galapunkta statusu; atgriešana uz active vienmēr ir jūsu lēmums.
• failing — tiek iestatīts automātiski, kad piegāde uz galapunktu izlieto visu atkārtošanas grafiku (8 mēģinājumi 24 stundu laikā), nekad nesaņemot 2xx. Galapunkts ar kļūmes statusu vairs nesaņem datplūsmu. Kad galapunkts ir salabots, ar PATCH atjauniniet tā statusu uz active; piegādes, kuru atkārtošanas grafiks vēl nav beidzies, turpinās no vietas, kur tās apstājās.

Uzskaitīt galapunktus#

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

Atgriež galapunktu objektu masīvu.

Izveidot galapunktu#

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

Pieprasījuma lauki#

Atgriež 201 Created ar galapunkta objektu un papildu augstākā līmeņa secret lauku, kas satur neapstrādātu parakstīšanas atslēgu — 48 rakstzīmju heksadecimālu virkni:

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

Atjaunināt galapunktu#

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

Atgriež 200 OK ar atjaunināto galapunkta objektu.

Nosūtiet testa piegādi#

Nosūtiet sintētisku webhook.test notikumu uz vienu galapunktu, izmantojot parasto piegādes plūsmu, tostarp kanonisko JSON serializāciju, X-ThunderPhone-Signature, piegādes reģistrēšanu un atkārtotu mēģinājumu uzskaiti. Tests ir vērsts uz atlasīto galapunktu neatkarīgi no tā events filtra.

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

Galapunkts saņem šādu aploksni:

{
  "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 pēc pirmā mēģinājuma atgriež 200 OK, pat ja galamērķis atgriež kļūdu. Pārbaudiet success, status, response_code un error, lai uzzinātu piegādes rezultātu:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test ir sintētisks un to nevar pievienot galapunkta events abonementam. Ja pirmais mēģinājums neizdodas, piegādei tiek izmantots tāds pats atkārtoto mēģinājumu grafiks kā parastām notikumu piegādēm.

Dzēsiet galapunktu#

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

Atgriež 204 No Content. Piegāde uz URL tiek nekavējoties pārtraukta; notiekošie atkārtotie mēģinājumi tiek atcelti.

Saistītā informācija#