Koncové body webhooků

Systém webhooků založený na koncových bodech umožňuje pro každou organizaci zaregistrovat více cílů, každý s vlastním tajným klíčem, vlastním stavem a vlastním odběrem podmnožiny typů událostí. Toto je doporučený model pro všechny nové integrace. Porovnejte jej se starším webhookem s jednou adresou URL, který je zachován kvůli zpětné kompatibilitě, ale podporuje pouze jednu adresu URL na organizaci.

Koncové body

Metoda	Cesta	Požadovaná role	Popis
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Vypíše koncové body
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Vytvoří koncový bod
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Aktualizuje štítek / URL / události / stav
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Odstraní koncový bod
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Odešle podepsané testovací doručení

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

Pole	Typ	Popis
`id`	UUID	ID koncového bodu
`label`	string	Zobrazovaný název, 1–120 znaků
`url`	string	Adresa HTTPS URL; pro vývoj je povoleno `http://localhost`
`events`	array of string	Typy odebíraných událostí (viz platné hodnoty). Prázdné pole odebírá všechny události
`status`	string	`active`, `disabled` (ručně pozastaveno) nebo `failing` (nastaví se automaticky, když doručení vyčerpá 24hodinový plán opakování, aniž by obdrželo jedinou odpověď 2xx)
`secret_hint`	string	První 4 a poslední 4 znaky tajného klíče pro podpis s výpustkou (`a1b2…9f0e`) — stačí k porovnání s tajným klíčem uloženým lokálně, aniž by se odhalila celá hodnota
`created_at`, `updated_at`	timestamp

Úplná hodnota secret koncového bodu se vrátí jednou při vytvoření a už nikdy znovu. Uložte ji bezpečně — pokud ji ztratíte, odstraňte koncový bod a vytvořte jej znovu.

Platné typy událostí

events se ověřuje vůči přesně této sadě — hodnoty mimo seznam vrátí 400. Tvar datové části jednotlivých typů naleznete v katalogu událostí.

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

Stavy koncových bodů

active — doručování probíhá normálně.
disabled — ručně pozastaveno pomocí PATCH. Neodesílají se žádné požadavky. Stav koncového bodu disabled nikdy neměníme; jeho přepnutí zpět na active je vždy na vás.
failing — nastaví se automaticky, když doručení do koncového bodu vyčerpá celý plán opakování (8 pokusů během 24 hodin), aniž by kdy obdrželo odpověď 2xx. Koncový bod ve stavu selhání nepřijímá žádný další provoz. Po opravě koncového bodu pomocí PATCH změňte jeho stav zpět na active; doručování, jehož plán opakování ještě nevypršel, bude pokračovat tam, kde skončilo.

Výpis koncových bodů

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

Vrátí pole objektů koncového bodu.

Vytvoření endpointu

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

Pole požadavku

Pole	Typ	Povinné	Popis
`label`	string	ano	1–120 znaků
`url`	string	ano	URL HTTPS (`http` je povoleno pouze pro `localhost` / `127.0.0.1`)
`events`	array	ne	Prázdné nebo vynechané pole přihlásí odběr všech událostí. Musí používat hodnoty uvedené v části Platné typy událostí; duplicity jsou odstraněny

Vrací 201 Created s objektem endpointu a dalším pole nejvyšší úrovně secret, které obsahuje nezpracovaný podpisový klíč — 48znakový hexadecimální řetězec:

{
  "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 se vrací pouze při vytvoření. Následné odpovědi GET obsahují pouze secret_hint. Před zavřením odpovědi zkopírujte úplnou hodnotu do správce tajných klíčů.

Aktualizace endpointu

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

Pole	Typ	Popis
`label`	string
`url`	string
`events`	array
`status`	string	`active` nebo `disabled`. Nastavením `active` znovu povolíte endpoint, který server označil jako `failing`

Vrací 200 OK s aktualizovaným objektem endpointu.

Odeslání testovacího doručení

Odešlete syntetickou událost webhook.test na jeden endpoint prostřednictvím standardního procesu doručování, včetně kanonické serializace JSON, X-ThunderPhone-Signature, záznamu o doručení a správy opakovaných pokusů. Test cílí na vybraný endpoint bez ohledu na jeho filtr events.

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

Endpoint obdrží obálku podobnou této:

{
  "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 vrátí 200 OK po prvním pokusu, i když cílové místo vrátí chybu. Výsledek doručení zjistíte v polích 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á událost a nelze ji přidat k odběru events endpointu. Pokud první pokus selže, doručení se řídí stejným harmonogramem opakovaných pokusů jako doručování běžných událostí.

Odstranění endpointu

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

Vrátí 204 No Content. Doručování na adresu URL se okamžitě zastaví; probíhající opakované pokusy budou zrušeny.

Související

Katalog událostí

Úplný seznam hodnot events, k jejichž odběru se můžete přihlásit.

Přehled webhooků

Ověření podpisu a sémantika doručování.

Webhooks

Function Tools

Koncové body webhooků

Koncové body

Objekt koncového bodu

Platné typy událostí

Stavy koncových bodů

Výpis koncových bodů

Vytvoření endpointu

Pole požadavku

Aktualizace endpointu

Odeslání testovacího doručení

Odstranění endpointu

Související

Katalog událostí

Přehled webhooků

​Koncové body

​Objekt koncového bodu

​Platné typy událostí

​Stavy koncových bodů

​Výpis koncových bodů

​Vytvoření endpointu

​Pole požadavku

​Aktualizace endpointu

​Odeslání testovacího doručení

​Odstranění endpointu

​Související

Katalog událostí

Přehled webhooků

Koncové body

Objekt koncového bodu

Platné typy událostí

Stavy koncových bodů

Výpis koncových bodů

Vytvoření endpointu

Pole požadavku

Aktualizace endpointu

Odeslání testovacího doručení

Odstranění endpointu

Související