> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Koncové body webhooků
> Spravujte více adres URL webhooků s tajnými klíči pro jednotlivé koncové body a filtry událostí.
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](/api-reference/organizations#legacy-single-url-webhook),
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
```json theme={null}
{
"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](#valid-event-types)). 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í](/cs/webhooks/events).
* `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ů
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Vrátí pole [objektů koncového bodu](#endpoint-object).
***
## Vytvoření endpointu
```bash cURL theme={null}
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"]
}'
```
```python Python theme={null}
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í](#valid-event-types); duplicity jsou odstraněny |
Vrací `201 Created` s [objektem endpointu](#endpoint-object) a dalším
pole nejvyšší úrovně `secret`, které obsahuje nezpracovaný podpisový klíč —
48znakový hexadecimální řetězec:
```json theme={null}
{
"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
```bash cURL theme={null}
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](#endpoint-object).
***
## 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`.
```bash cURL theme={null}
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:
```json theme={null}
{
"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`:
```json theme={null}
{
"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
```bash cURL theme={null}
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í
Úplný seznam hodnot `events`, k jejichž odběru se můžete přihlásit.
Ověření podpisu a sémantika doručování.