---
title: "Koncové body webhooků"
description: "Spravujte více adres URL webhooků s tajnými klíči a filtry událostí pro jednotlivé koncové body."
---

Systém webhooků založený na koncových bodech vám umožňuje zaregistrovat **více**
cílů pro každou organizaci, přičemž každý má vlastní tajný klíč, vlastní
stav a vlastní odběr 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+` | Vypsat endpointy |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Vytvořit endpoint |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Aktualizovat štítek / URL / události / stav |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Odstranit endpoint |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Nahradit tajný klíč pro podpis |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Odeslat podepsané testovací doručení |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Zkontrolovat nedávné výsledky doručení endpointů a starších doručení |

## Objekt koncového bodu

```json
{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "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` | řetězec | Zobrazovaný název, 1–120 znaků |
| `url` | řetězec | Adresa URL HTTPS; pro vývoj je povoleno `http://localhost` |
| `events` | pole řetězců | Typy odebíraných událostí (viz [platné hodnoty](#valid-event-types)). Prázdné pole odebírá všechny události kromě událostí jednotlivých tahů dostupných pouze při výslovném odběru (`telephony.turn` / `web.turn`) |
| `status` | řetězec | `active`, `disabled` (ručně pozastaveno) nebo `failing` (nastaví se automaticky, když doručení vyčerpá svůj 24hodinový plán opakování bez jediného 2xx) |
| `agent_id` | celé číslo \| null | Hlasový agent, pro kterého je tento koncový bod vymezen; `null` znamená pro celou organizaci |
| `agent_name` | řetězec \| null | Název hlasového agenta, pro kterého je koncový bod vymezen, nebo `null` pro koncový bod platný pro celou organizaci |
| `secret_hint` | řetězec | První 4 a poslední 4 znaky podpisového tajného klíče 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 |
| `paused_at` | časové razítko \| null | Kdy ThunderPhone nastavil koncový bod na `failing`. `null`, dokud je `active` nebo `disabled` |
| `pause_last_error` | řetězec | Poslední chyba doručení při pozastavení koncového bodu, například `HTTP 503: Service Unavailable`. Prázdné, pokud stav není `failing` |
| `pause_undelivered_count` | celé číslo \| null | Události nedoručené od posledního úspěšného doručení koncového bodu, započítané při jeho pozastavení |
| `created_at`, `updated_at` | časové razítko | |

<Note>
  Úplný `secret` endpointu je při vytvoření vrácen **pouze jednou** a
  už nikdy znovu. Uložte jej bezpečně — pokud ho ztratíte,
  [obnovte jej](#rotate-the-signing-secret) a získejte nový.
</Note>

### Platné typy událostí

`events` se ověřuje podle přesně této sady — hodnoty mimo seznam
vrátí `400`. Tvar datové části jednotlivých typů najdete v [katalogu událostí](/cs/webhooks/events).

- `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `sms.sent`, `sms.failed`
- `sms.received` (rezervováno; zatím se nevysílá)
- `call.graded`, `call.data_extracted`, `call.transfer_completed`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`

`issue.escalated` nemá kontext agenta a doručuje se pouze koncovým bodům
pro celou organizaci.

`voice.ready` a `voice.failed` nelze vybrat explicitně. Chcete-li je přijímat,
vytvořte koncový bod pro celou organizaci s `events: []`. Prázdný seznam událostí
přijímá všechny podporované události kromě `telephony.turn` a `web.turn`,
které musí být vybrány explicitně.

### Stavy koncového bodu

- `active` — doručování probíhá normálně.
- `disabled` — ručně pozastaveno pomocí `PATCH`. Neodesílají se žádné požadavky. Stav endpointu `disabled` nikdy neměníme; o jeho přepnutí zpět na `active` vždy rozhodujete vy.
- `failing` — nastaví se automaticky, když doručování do endpointu vyčerpá celý plán opakování (8 pokusů během 24 hodin), aniž by kdy obdrželo odpověď 2xx. Endpoint ve stavu selhání nepřijímá žádný další provoz. Když k tomu dojde, odešleme e-mail vlastníkům a správcům vaší organizace a řídicí panel zobrazí pozastavený endpoint s tlačítkem Znovu aktivovat. Po opravě endpointu 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ů

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Vrací pole [objektů koncových bodů](#endpoint-object).
Předejte `?agent_id=42`, chcete-li vrátit pouze koncové body omezené na tohoto agenta.

### Koncové body omezené na agenta

Koncové body pro celou organizaci přijímají všechny odpovídající události. Koncový bod s
`agent_id` přijímá pouze odpovídající události pro hovory vyřízené daným agentem;
události bez kontextu agenta, jako například `alert.triggered`, jej nikdy nedosáhnou. Tyto
koncové body můžete také vytvářet a spravovat v sekci
**Webhooky** editoru agenta.

---

## Vytvoření endpointu

<CodeGroup>
```bash cURL
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
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"]
```
</CodeGroup>

### Pole požadavku

| Pole | Typ | Povinné | Popis |
|-------|------|----------|-------------|
| `label` | řetězec | ano | 1–120 znaků |
| `url` | řetězec | ano | HTTPS URL (`http` je povoleno pouze pro `localhost` / `127.0.0.1`) |
| `events` | pole | ne | Prázdné/vynechané pole přihlásí odběr všech událostí kromě `telephony.turn` / `web.turn`, které vyžadují výslovný odběr. Musí používat hodnoty uvedené v části [Platné typy událostí](#valid-event-types); duplicity jsou odstraněny |
| `agent_id` | celé číslo \| null | ne | Omezí doručování na agenta v této organizaci; pro endpoint platný pro celou organizaci pole vynechte nebo použijte `null` |

Vrací `201 Created` s [objektem endpointu](#endpoint-object) a dalším
polem `secret` na nejvyšší úrovni obsahujícím nezpracovaný podpisový klíč —
48znakový hexadecimální řetězec:

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

<Warning>
  `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íčů.
</Warning>

---

## Aktualizace endpointu

<CodeGroup>
```bash cURL
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"]
  }'
```
</CodeGroup>

| Pole | Typ | Popis |
|-------|------|-------------|
| `label` | řetězec | |
| `url` | řetězec | |
| `events` | pole | |
| `status` | řetězec | `active` nebo `disabled`. Nastavením `active` znovu povolíte endpoint, který server označil jako `failing` |
| `agent_id` | celé číslo \| null | Nastavte ID agenta pro omezení endpointu, nebo `null`, aby platil pro celou organizaci |

Vrací `200 OK` s aktualizovaným [objektem endpointu](#endpoint-object).

---

## Obnovení podpisového tajemství

Nahraďte podpisové tajemství endpointu, například pokud se ztratilo nebo
mohlo uniknout. Pro endpoint vázaný na agenta můžete také použít
dashboard: otevřete sekci **Webhooky** agenta a u endpointu vyberte
**Znovu vygenerovat tajemství**. Endpointy platné pro celou organizaci se
obnovují prostřednictvím API.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
</CodeGroup>

| Pole | Typ | Povinné | Popis |
|-------|------|----------|-------------|
| `include_copies` | boolean | ne | Výchozí hodnota je `true`. Nové tajemství také přiřadí ostatním endpointům vaší organizace, které mají stejnou adresu URL a stejné aktuální tajemství, například kopiím tohoto endpointu u jiných agentů, aby jeden příjemce nadále ověřoval pomocí jednoho tajemství |

Vrací `200 OK`:

```json
{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
```

| Pole | Typ | Popis |
|-------|------|-------------|
| `endpoint` | object | [Objekt endpointu](#endpoint-object) s novým `secret_hint` |
| `secret` | string | Nové podpisové tajemství. Vrací se pouze v této odpovědi |
| `rotated_endpoint_ids` | pole UUID | Každý endpoint, který nyní používá nové tajemství |

<Warning>
  Staré tajemství se přestane používat okamžitě: následující doručení,
  včetně opakovaných pokusů, je podepsáno novým tajemstvím. Dokud váš příjemce nemá
  nové tajemství, doručení neprojdou kontrolou podpisu; pokud na ně odpoví
  stavem jiným než 2xx, budou se opakovat podle běžného 24hodinového
  plánu, proto příjemce neprodleně aktualizujte. Pokud příjemce nasazujete
  postupně, nechte jej během nasazování přijímat obě tajemství — pomocné funkce SDK
  pro ověření přijímají seznam tajemství (viz
  [Ověření podpisů webhooků](/cs/guides/verify-webhook-signatures)).
</Warning>

---

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

Odešlete syntetickou událost `webhook.test` do jednoho endpointu pomocí standardního
procesu doručení, včetně kanonické serializace JSON, obou
hlaviček podpisu, záznamu o doručení a evidence opakovaných pokusů.
Test cílí na vybraný endpoint bez ohledu na jeho filtr `events`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Koncový bod obdrží obálku podobnou této:

```json
{
  "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íl vrátí chybu.
Výsledek doručení zjistíte kontrolou `success`, `status`, `response_code` a `error`:

```json
{
  "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`
koncového bodu. Pokud první pokus selže, ThunderPhone jej přibližně
o minutu později jednou zopakuje a poté se zastaví; doručení pak zobrazí
`status: "failed"` v části [Ladění doručení](#debug-deliveries). Testovací doručení nikdy neoznačí
koncový bod jako `failing`.

Chcete-li nakonfigurovat spouštěč pro skutečnou strukturu události, předejte volitelný
parametr `event_type`. Doručení je stále syntetické a obsahuje `"sample": true`;
ukázky související s hovory používají `call_id: 0` a `agent_id: 0`.

```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'
```

`event_type` přijímá libovolnou hodnotu z [Platných typů událostí](#valid-event-types).
Jeho vynechání zachová obecné chování `webhook.test`.

---

## Odstranění koncového bodu

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

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

---

## Ladění doručení

Než dospějete k závěru, že webhook nebyl odeslán, zkontrolujte
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Zobrazuje nedávné pokusy z obou systémů webhooků, včetně ID hovoru,
původu URL, stavu HTTP, počtu pokusů, kategorie povoleného selhání a času dalšího
opakovaného pokusu. Nikdy nevrací datovou část události, přepis, uložený text chyby,
tělo odpovědi ani cestu URL.

Stejnou nedávnou historii můžete zobrazit také v části **Agenti → vyberte agenta → Webhooky →
Poslední doručení**. Řádky zobrazují štítek koncového bodu a původ URL použitý při posledním
pokusu. Jde o provozní stav, nikoli neměnný auditní záznam: odstraněním koncového bodu
se odstraní také jeho řádky doručení.

U chyby n8n `404` nejprve ověřte, že je pracovní postup aktivní, přijímá `POST` a používá
produkční URL webhooku namísto testovací URL. Chyba `401` nebo `403` ukazuje na
ověřování nebo validaci podpisu; časové limity ukazují na latenci
nebo dostupnost cíle; chyby TLS ukazují na řetězec certifikátů, název hostitele nebo platnost.

---

## Související

<CardGroup cols={2}>
  <Card title="Katalog událostí" icon="list" href="/cs/webhooks/events">
    Úplný seznam hodnot `events`, které můžete odebírat.
  </Card>
  <Card title="Přehled webhooků" icon="bolt" href="/cs/webhooks/overview">
    Ověřování podpisu a sémantika doručení.
  </Card>
</CardGroup>