Webhook крайни точки

Управлявайте множество webhook URL адреси с тайни за всяка крайна точка и филтри за събития.

Базираната на крайни точки webhook система ви позволява да регистрирате няколко дестинации за организация, всяка със собствена тайна, собствен статус и собствен абонамент за подмножество от типове събития. Това е препоръчителният модел за всички нови интеграции.

Сравнете с наследения webhook с един URL, който се поддържа за обратна съвместимост, но поддържа само един URL за организация.

Крайни точки#

Обект на крайна точка#

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

Валидни типове събития#

events се валидира спрямо точно този набор — стойности извън списъка връщат 400. Вижте Каталог на събитията за структурата на полезния товар за всеки тип.

• 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; доставките, чийто график за повторни опити все още не е изтекъл, продължават оттам, докъдето са стигнали.

Списък с крайни точки#

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

Връща масив от обекти на крайни точки. Подайте ?agent_id=42, за да върнете само крайните точки, ограничени до този агент.

Крайни точки, ограничени до агент#

Крайните точки за цялата организация получават всяко съответстващо събитие. Крайна точка с agent_id получава само съответстващи събития за обаждания, обработвани от този агент; събития без контекст на агент, като alert.triggered, никога не достигат до нея. Можете също да създавате и управлявате тези крайни точки от секцията Уебкуки в конструктора на агента.

Създаване на крайна точка#

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

Полета на заявката#

Връща 201 Created с обекта на крайната точка плюс допълнително поле secret от най-горно ниво, съдържащо необработения ключ за подписване — 48-знаков шестнадесетичен низ:

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

Актуализиране на крайна точка#

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

Връща 200 OK с актуализирания обект на крайната точка.

Изпращане на тестова доставка#

Изпратете синтетично събитие webhook.test до една крайна точка чрез стандартния конвейер за доставка, включително канонична JSON сериализация, X-ThunderPhone-Signature, записване на доставката и проследяване на повторните опити. Тестът е насочен към избраната крайна точка независимо от нейния филтър events.

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

Крайната точка получава обвивка като тази:

{
  "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 за резултата от доставката:

{
  "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.

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 приема всяка стойност от Валидни типове събития. Ако го пропуснете, се запазва общото поведение на webhook.test.

Изтриване на крайна точка#

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. Той показва последните опити от двете системи за уебхукове, включително ID на обаждането, произхода на URL адреса, HTTP статуса, броя опити, категорията на неуспех от списъка с разрешени стойности и времето за следващия повторен опит. Никога не връща полезния товар на събитието, транскрипцията, съхранения текст на грешката, тялото на отговора или пътя на URL адреса.

Можете също да видите същата скорошна история в Агенти → изберете агент → Уебхукове → Последни доставки. Редовете показват етикета на крайната точка и произхода на URL адреса, използван при последния опит. Това е оперативно състояние, а не неизменяем одитен дневник: изтриването на крайна точка изтрива и нейните редове за доставки.

При 404 от n8n първо потвърдете, че работният поток е активен, приема POST и използва URL адреса на уебхука за продукционна среда, а не тестовия URL адрес. 401 или 403 сочи към удостоверяване или валидиране на подписа; изчакванията сочат към забавяне или недостъпност на местоназначението; TLS грешките сочат към веригата от сертификати, името на хоста или изтичането му.

Свързано#