---
title: "Webhook крайни точки"
description: "Управлявайте множество webhook URL адреси с тайни за всяка крайна точка и филтри за събития."
---
Базираната на крайни точки webhook система ви позволява да регистрирате **няколко**
дестинации за организация, всяка със собствена тайна, собствен
статус и собствен абонамент за подмножество от типове събития. Това е
препоръчителният модел за всички нови интеграции.
Сравнете с [наследения webhook с един URL](/api-reference/organizations#legacy-single-url-webhook),
който се поддържа за обратна съвместимост, но поддържа само един URL за
организация.
## Крайни точки
| Метод | Път | Изисквана роля | Описание |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Извеждане на списък с крайни точки |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Създаване на крайна точка |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Актуализиране на етикет / URL / събития / статус |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Изтриване на крайна точка |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Изпращане на подписана тестова доставка |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Преглед на последните резултати от доставки за крайни точки и наследени доставки |
## Обект на крайна точка
```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"
}
```
| Поле | Тип | Описание |
|-------|------|-------------|
| `id` | UUID | Идентификатор на крайната точка |
| `label` | string | Показвано име, 1–120 символа |
| `url` | string | HTTPS URL; `http://localhost` е разрешен за разработка |
| `events` | масив от string | Типове събития с абонамент (вижте [валидните стойности](#valid-event-types)). Празен масив се абонира за всички събития с изключение на изрично избираемите събития за всеки ход (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (ръчно поставена на пауза) или `failing` (задава се автоматично, когато доставката изчерпи своя 24-часов график за повторни опити без нито един 2xx) |
| `agent_id` | integer \| null | Агентът, към който е ограничена тази крайна точка; `null` означава за цялата организация |
| `agent_name` | string \| null | Името на агента, към когото е ограничена крайната точка, или `null` за крайна точка за цялата организация |
| `secret_hint` | string | Първите 4 и последните 4 знака от тайната за подписване с многоточие (`a1b2…9f0e`) — достатъчно, за да сверите тайната, която сте запазили локално, без да разкривате пълната стойност |
| `created_at`, `updated_at` | timestamp | |
Пълният `secret` на крайната точка се връща **само веднъж** при създаване и
никога повече. Съхранявайте го сигурно — ако го изгубите, изтрийте крайната точка
и я създайте отново.
### Валидни типове събития
`events` се валидира спрямо точно този набор — стойности извън списъка
връщат `400`. Вижте [Каталог на събитията](/bg/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` няма контекст на агент и се доставя само до
крайни точки за цялата организация.
`voice.ready` и `voice.failed` не могат да бъдат избирани изрично. За да ги
получавате, създайте крайна точка за цялата организация с `events: []`. Празен списък
със събития получава всяко поддържано събитие с изключение на `telephony.turn` и `web.turn`,
които трябва да бъдат избрани изрично.
### Статуси на крайните точки
- `active` — доставките протичат нормално.
- `disabled` — ръчно поставена на пауза чрез `PATCH`. Не се изпращат заявки. Ние
никога не променяме статуса на крайна точка с `disabled`; връщането му на
`active` винаги е ваше решение.
- `failing` — задава се автоматично, когато доставка до крайната точка
изчерпи целия си график за повторни опити (8 опита за 24 часа), без
да получи нито един 2xx. Крайна точка с неуспешен статус не получава допълнителен трафик.
След като коригирате крайната точка, променете чрез `PATCH` статуса ѝ обратно на `active`;
доставките, чийто график за повторни опити все още не е изтекъл, продължават оттам,
докъдето са стигнали.
---
## Списък с крайни точки
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Връща масив от [обекти на крайни точки](#endpoint-object).
Подайте `?agent_id=42`, за да върнете само крайните точки, ограничени до този агент.
### Крайни точки, ограничени до агент
Крайните точки за цялата организация получават всяко съответстващо събитие. Крайна точка с
`agent_id` получава само съответстващи събития за обаждания, обработвани от този агент;
събития без контекст на агент, като `alert.triggered`, никога не достигат до нея. Можете
също да създавате и управлявате тези крайни точки от секцията
**Уебкуки** в конструктора на агента.
---
## Създаване на крайна точка
```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"]
```
### Полета на заявката
| Поле | Тип | Задължително | Описание |
|-------|------|----------|-------------|
| `label` | низ | да | 1–120 знака |
| `url` | низ | да | HTTPS URL (`http` е разрешен само за `localhost` / `127.0.0.1`) |
| `events` | масив | не | Празна или пропусната стойност се абонира за всички събития с изключение на `telephony.turn` / `web.turn`, за които е необходимо изрично абониране. Трябва да използвате стойностите, изброени във [Валидни типове събития](#valid-event-types); дубликатите се премахват |
| `agent_id` | цяло число \| null | не | Ограничава доставянето до агент в тази организация; пропуснете или използвайте `null` за крайна точка за цялата организация |
Връща `201 Created` с [обекта на крайната точка](#endpoint-object) плюс
допълнително поле `secret` от най-горно ниво, съдържащо необработения ключ за подписване —
48-знаков шестнадесетичен низ:
```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"
}
```
`secret` се връща **само при създаване**. Последващите отговори от `GET`
включват само `secret_hint`. Копирайте пълната стойност във вашия мениджър
за тайни, преди да затворите отговора.
---
## Актуализиране на крайна точка
```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"]
}'
```
| Поле | Тип | Описание |
|-------|------|-------------|
| `label` | низ | |
| `url` | низ | |
| `events` | масив | |
| `status` | низ | `active` или `disabled`. Задайте `active`, за да активирате отново крайна точка, която сървърът е маркирал като `failing` |
| `agent_id` | цяло число \| null | Задайте идентификатор на агент, за да ограничите крайната точка, или `null`, за да я направите за цялата организация |
Връща `200 OK` с актуализирания [обект на крайната точка](#endpoint-object).
---
## Изпращане на тестова доставка
Изпратете синтетично събитие `webhook.test` до една крайна точка чрез стандартния
конвейер за доставка, включително канонична JSON сериализация,
`X-ThunderPhone-Signature`, записване на доставката и проследяване на повторните опити.
Тестът е насочен към избраната крайна точка независимо от нейния филтър `events`.
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Крайната точка получава обвивка като тази:
```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 връща `200 OK` след първия опит, дори ако местоназначението
върне грешка. Проверете `success`, `status`, `response_code` и `error`
за резултата от доставката:
```json
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
`webhook.test` е синтетично и не може да бъде добавено към абонамента `events`
на крайна точка. Ако първият опит е неуспешен, доставката следва същия
график за повторни опити като стандартните доставки на събития.
За да конфигурирате задействане спрямо формата на реално събитие, подайте незадължителен
`event_type`. Доставката остава синтетична и съдържа `"sample": true`;
примерите, свързани с обаждания, използват `call_id: 0` и `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` приема всяка стойност от [Валидни типове събития](#valid-event-types).
Ако го пропуснете, се запазва общото поведение на `webhook.test`.
---
## Изтриване на крайна точка
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Връща `204 No Content`. Доставката до URL адреса спира незабавно;
повторните опити в ход се прекратяват.
---
## Отстраняване на проблеми с доставките
Преди да заключите, че уебхук не е изпратен, проверете
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Той показва последните опити от двете системи за уебхукове, включително ID на обаждането,
произхода на URL адреса, HTTP статуса, броя опити, категорията на неуспех от списъка с разрешени стойности и времето за следващия
повторен опит. Никога не връща полезния товар на събитието, транскрипцията, съхранения текст на грешката,
тялото на отговора или пътя на URL адреса.
Можете също да видите същата скорошна история в **Агенти → изберете агент → Уебхукове →
Последни доставки**. Редовете показват етикета на крайната точка и произхода на URL адреса, използван при последния
опит. Това е оперативно състояние, а не неизменяем одитен дневник: изтриването на крайна точка
изтрива и нейните редове за доставки.
При `404` от n8n първо потвърдете, че работният поток е активен, приема `POST` и използва
URL адреса на уебхука за продукционна среда, а не тестовия URL адрес. `401` или `403` сочи към
удостоверяване или валидиране на подписа; изчакванията сочат към забавяне
или недостъпност на местоназначението; TLS грешките сочат към веригата от сертификати, името на хоста или изтичането му.
---
## Свързано
Пълният списък със стойности на `events`, за които можете да се абонирате.
Проверка на подписа и семантика на доставката.