Koncové body webhookov

Systém webhookov založený na koncových bodoch vám umožňuje zaregistrovať viacero cieľov pre každú organizáciu, pričom každý má vlastné tajomstvo, vlastný stav a vlastné odoberanie podmnožiny typov udalostí. Toto je odporúčaný model pre všetky nové integrácie.

Porovnajte ho so starším webhookom s jednou adresou URL, ktorý sa zachováva kvôli spätnej kompatibilite, ale podporuje iba jednu adresu URL na organizáciu.

Koncové body

Objekt koncového bodu

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

Platné typy udalostí

events sa overuje podľa tejto presnej množiny — hodnoty mimo zoznamu vrátia 400. Tvar údajov každého typu nájdete v katalógu udalostí.

• telephony.incoming, telephony.complete, telephony.tool
• web.incoming, web.complete, web.tool
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

Stavy koncových bodov

• active — doručenia prebiehajú normálne.
• disabled — manuálne pozastavený prostredníctvom PATCH. Neodosielajú sa žiadne požiadavky. Stav koncového bodu disabled nikdy nemeníme; jeho prepnutie späť na active je vždy na vás.
• failing — nastaví sa automaticky, keď doručenie do koncového bodu vyčerpá celý plán opakovaných pokusov (8 pokusov počas 24 hodín) bez jedinej odpovede 2xx. Koncový bod v stave zlyhania neprijíma žiadnu ďalšiu prevádzku. Po oprave koncového bodu nastavte pomocou PATCH jeho stav späť na active; doručenia, ktorých plán opakovaných pokusov ešte nevypršal, budú pokračovať tam, kde skončili.

Zoznam koncových bodov

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

Vráti pole objektov koncových bodov.

Vytvorenie koncového bodu

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

Polia požiadavky

Vracia 201 Created s objektom koncového bodu a ďalším poľom secret na najvyššej úrovni, ktoré obsahuje nespracovaný podpisový kľúč — 48-znakový hexadecimálny reťazec:

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

Aktualizácia koncového bodu

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

Vracia 200 OK s aktualizovaným objektom koncového bodu.

Odoslanie testovacieho doručenia

Odošlite syntetickú udalosť webhook.test na jeden koncový bod prostredníctvom štandardného procesu doručovania vrátane kanonickej serializácie JSON, X-ThunderPhone-Signature, záznamu o doručení a správy opakovaných pokusov. Test je zacielený na vybraný koncový bod bez ohľadu na jeho filter events.

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

Koncový bod prijme obálku podobnú tejto:

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

Rozhranie API vráti 200 OK po prvom pokuse, aj keď cieľ vráti chybu. Výsledok doručenia skontrolujte v poliach success, status, response_code a error:

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

webhook.test je syntetická udalosť a nemožno ju pridať do odberu events koncového bodu. Ak prvý pokus zlyhá, doručenie sa riadi rovnakým harmonogramom opakovaných pokusov ako bežné doručenia udalostí.

Odstrániť endpoint

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

Vráti 204 No Content. Doručovanie na URL sa okamžite zastaví; opakované pokusy počas spracovania sa zrušia.

Súvisiace