---
title: "Koncové body webhookov"
description: "Spravujte viacero adries URL webhookov s tajnými kľúčmi a filtrami udalostí pre jednotlivé koncové body."
---
Systém webhookov založený na koncových bodoch vám umožňuje zaregistrovať **viacero**
cieľov pre organizáciu, pričom každý má vlastné tajomstvo, vlastný
stav a vlastné predplatné podmnožiny typov udalostí. Toto je
odporúčaný model pre všetky nové integrácie.
Porovnajte so [starším webhookom s jednou URL](/api-reference/organizations#legacy-single-url-webhook),
ktorý je zachovaný kvôli spätnej kompatibilite, ale podporuje iba jednu URL pre
organizáciu.
## Koncové body
| Metóda | Cesta | Požadovaná rola | Popis |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Zoznam koncových bodov |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Vytvoriť koncový bod |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Aktualizovať označenie / URL / udalosti / stav |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Odstrániť koncový bod |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Odoslať podpísané testovacie doručenie |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Skontrolovať nedávne výsledky doručení koncových bodov a starších webhookov |
## 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",
"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ázov, 1–120 znakov |
| `url` | string | HTTPS URL; `http://localhost` je povolené pre vývoj |
| `events` | pole stringov | Typy odoberaných udalostí (pozrite si [platné hodnoty](#valid-event-types)). Prázdne pole odoberá všetky udalosti okrem udalostí explicitne vyžadovaných pre každé kolo (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (manuálne pozastavené) alebo `failing` (nastaví sa automaticky, keď doručenie vyčerpá 24-hodinový harmonogram opakovaných pokusov bez jedinej odpovede 2xx) |
| `agent_id` | integer \| null | Hlasový agent, na ktorého je tento koncový bod obmedzený; `null` znamená celú organizáciu |
| `agent_name` | string \| null | Názov hlasového agenta v rozsahu koncového bodu alebo `null` pre koncový bod platný pre celú organizáciu |
| `secret_hint` | string | Prvé 4 a posledné 4 znaky podpisového tajomstva s elipsou (`a1b2…9f0e`) — stačí na porovnanie s tajomstvom, ktoré ste uložili lokálne, bez odhalenia celej hodnoty |
| `created_at`, `updated_at` | timestamp | |
Úplné `secret` koncového bodu sa pri vytvorení vráti **iba raz** a
už nikdy viac. Bezpečne ho uložte — ak ho stratíte, odstráňte koncový bod
a vytvorte ho znova.
### Platné typy udalostí
`events` sa overuje voči tejto presnej množine — hodnoty mimo zoznamu
vrátia `400`. Tvar údajov každého typu nájdete v [katalógu udalostí](/sk/webhooks/events).
- `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `call.graded`, `call.data_extracted`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`
`issue.escalated` nemá kontext hlasového agenta a doručuje sa iba do
koncových bodov platných pre celú organizáciu.
`voice.ready` a `voice.failed` nemožno vybrať explicitne. Ak ich chcete prijímať,
vytvorte koncový bod platný pre celú organizáciu s `events: []`. Prázdny zoznam
udalostí prijíma každú podporovanú udalosť okrem `telephony.turn` a `web.turn`,
ktoré je nutné vybrať explicitne.
### Stavy koncových bodov
- `active` — doručovanie prebieha normálne.
- `disabled` — manuálne pozastavené prostredníctvom `PATCH`. Neodosielajú sa
žiadne požiadavky. Stav koncového bodu `disabled` nikdy nemeníme; rozhodnutie
prepnúť ho späť na `active` je vždy na vás.
- `failing` — nastaví sa automaticky, keď doručenie do koncového bodu vyčerpá
celý harmonogram opakovaných pokusov (8 pokusov počas 24 hodín) bez získania
odpovede 2xx. Koncový bod v stave zlyhania neprijíma žiadnu ďalšiu prevádzku.
Po oprave koncového bodu zmeňte jeho stav pomocou `PATCH` späť na `active`;
doručovania, ktorých harmonogram opakovaných pokusov ešte nevypršal, budú
pokračovať tam, kde skončili.
---
## Zoznam koncových bodov
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Vráti pole [objektov koncových bodov](#endpoint-object).
Ak chcete vrátiť iba koncové body obmedzené na daného hlasového agenta, pridajte `?agent_id=42`.
### Koncové body obmedzené na hlasového agenta
Koncové body platné pre celú organizáciu prijímajú každú zodpovedajúcu udalosť. Koncový bod s
`agent_id` prijíma iba zodpovedajúce udalosti pre hovory spracované daným hlasovým agentom;
udalosti bez kontextu hlasového agenta, napríklad `alert.triggered`, sa k nemu nikdy
nedostanú. Tieto koncové body môžete vytvárať a spravovať aj v sekcii
**Webhooky** v nástroji na tvorbu hlasových agentov.
---
## Vytvorte koncový bod
```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"]
```
### Polia požiadavky
| Pole | Typ | Povinné | Popis |
|-------|------|----------|-------------|
| `label` | reťazec | áno | 1–120 znakov |
| `url` | reťazec | áno | URL adresa HTTPS (`http` je povolené iba pre `localhost` / `127.0.0.1`) |
| `events` | pole | nie | Prázdna alebo vynechaná hodnota prihlási na odber všetkých udalostí okrem `telephony.turn` / `web.turn`, ktoré vyžadujú explicitné prihlásenie na odber. Musíte použiť hodnoty uvedené v časti [Platné typy udalostí](#valid-event-types); duplicity sa odstránia |
| `agent_id` | celé číslo \| null | nie | Obmedzte doručovanie na hlasového agenta v tejto organizácii; pre koncový bod pre celú organizáciu pole vynechajte alebo použite `null` |
Vráti `201 Created` s [objektom koncového bodu](#endpoint-object) a dodatočným
poľom najvyššej úrovne `secret`, ktoré obsahuje nespracovaný podpisový kľúč —
48-znakový hexadecimálny reťazec:
```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"
}
```
Hodnota `secret` sa vráti **iba pri vytvorení**. Nasledujúce odpovede `GET`
obsahujú iba hodnotu `secret_hint`. Pred zatvorením odpovede skopírujte
úplnú hodnotu do správcu tajomstiev.
---
## Aktualizujte koncový bod
```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"]
}'
```
| Pole | Typ | Popis |
|-------|------|-------------|
| `label` | reťazec | |
| `url` | reťazec | |
| `events` | pole | |
| `status` | reťazec | `active` alebo `disabled`. Nastavte hodnotu `active`, aby ste znova povolili koncový bod, ktorý server označil ako `failing` |
| `agent_id` | celé číslo \| null | Nastavte ID hlasového agenta na obmedzenie koncového bodu alebo `null`, aby bol dostupný pre celú organizáciu |
Vráti `200 OK` s aktualizovaným [objektom koncového bodu](#endpoint-object).
---
## Odoslanie testovacej doručovacej požiadavky
Odošlite syntetickú udalosť `webhook.test` na jeden endpoint pomocou štandardného
procesu doručovania vrátane kanonickej serializácie JSON,
`X-ThunderPhone-Signature`, zaznamenania doručovania a správy opakovaných pokusov.
Test je zameraný na vybraný endpoint bez ohľadu na jeho filter `events`.
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Endpoint dostane obálku podobnú tejto:
```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 po prvom pokuse vráti `200 OK`, aj keď cieľ vráti chybu.
Výsledok doručenia skontrolujte v poliach `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á udalosť a nemožno ju pridať do odberu `events`
endpointu. Ak prvý pokus zlyhá, doručenie sa riadi rovnakým
plánom opakovaných pokusov ako doručovanie bežných udalostí.
Ak chcete nakonfigurovať spúšťač podľa tvaru skutočnej udalosti, odovzdajte voliteľný
parameter `event_type`. Doručenie je stále syntetické a obsahuje `"sample": true`;
vzorky súvisiace s hovormi 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` prijíma ľubovoľnú hodnotu zo zoznamu [Platné typy udalostí](#valid-event-types).
Jeho vynechaním zachováte všeobecné správanie `webhook.test`.
---
## Odstránenie endpointu
```bash cURL
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í;
prebiehajúce opakované pokusy sa zrušia.
---
## Ladenie doručení
Skôr než usúdite, že webhook nebol odoslaný, skontrolujte
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Zobrazuje nedávne pokusy z oboch webhookových systémov vrátane ID hovoru,
pôvodu URL, stavu HTTP, počtu pokusov, kategórie chýb zo zoznamu povolených hodnôt a času
ďalšieho opakovania. Nikdy nevracia payload udalosti, prepis, uložený text chyby,
telo odpovede ani cestu URL.
Rovnakú nedávnu históriu si môžete zobraziť aj v **Agenti → vyberte agenta → Webhooky →
Nedávne doručenia**. Riadky zobrazujú označenie endpointu a pôvod URL použitý pri najnovšom
pokuse. Ide o prevádzkový stav, nie o nemenný auditný záznam: odstránením endpointu
sa odstránia aj jeho riadky doručení.
Pri chybe n8n `404` najprv potvrďte, že je pracovný postup aktívny, prijíma `POST` a používa
produkčnú URL webhooku, nie testovaciu URL. Kód `401` alebo `403` naznačuje problém
s autentifikáciou alebo overením podpisu; časové limity naznačujú latenciu
alebo dostupnosť cieľa; chyby TLS naznačujú problém s reťazcom certifikátov, názvom hostiteľa alebo platnosťou.
---
## Súvisiace
Úplný zoznam hodnôt `events`, ktoré môžete odoberať.
Overovanie podpisov a sémantika doručovania.