Конечные точки вебхуков

Управляйте несколькими URL-адресами вебхуков с секретами и фильтрами событий для каждой конечной точки.

Система вебхуков на основе эндпоинтов позволяет регистрировать несколько назначений для каждой организации, у каждого из которых есть собственный секрет, статус и подписка на подмножество типов событий. Это рекомендуемая модель для всех новых интеграций.

Сравните с устаревшим вебхуком с одним 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",
  "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"
}

Допустимые типы событий#

events проверяется по этому точному набору — значения вне списка возвращают 400. Формат полезной нагрузки каждого типа см. в каталоге событий.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (зарезервировано; пока не отправляется)
• call.graded, call.data_extracted, call.transfer_completed
• 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. Конечная точка в состоянии сбоя больше не получает трафик. В этом случае мы отправляем письмо по email владельцам и администраторам вашей организации, а на панели управления отображается приостановленная конечная точка с кнопкой «Повторно активировать». После исправления конечной точки верните её статус в active через PATCH; доставки, график повторных попыток которых ещё не исчерпан, продолжатся с того места, на котором остановились.

Список конечных точек#

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 с обновлённым объектом эндпоинта.

Смена секрета подписи#

Замените секрет подписи конечной точки, например если он был утерян или мог быть раскрыт. Для конечной точки уровня агента также можно использовать панель управления: откройте раздел агента Вебхуки и выберите для конечной точки Сгенерировать новый секрет. Секреты конечных точек уровня организации меняются через API.

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

Возвращает 200 OK:

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

Отправить тестовую доставку#

Отправьте синтетическое событие webhook.test на один эндпоинт через стандартный конвейер доставки, включая каноническую сериализацию JSON, оба заголовка подписи, запись доставки и учёт повторных попыток. Тест нацелен на выбранный эндпоинт независимо от его фильтра 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 конечной точки. Если первая попытка завершится неудачей, ThunderPhone повторит её один раз примерно через минуту, а затем остановится; после этого доставка будет иметь status: "failed" в разделе Отладка доставок. Тестовая доставка никогда не переводит конечную точку в состояние failing.

Чтобы настроить триггер для структуры реального события, передайте необязательный 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. Он показывает недавние попытки из обеих систем вебхуков, включая идентификатор звонка, источник URL, HTTP-статус, число попыток, категорию сбоя из разрешённого списка и время следующей повторной попытки. Он никогда не возвращает полезную нагрузку события, расшифровку, сохранённый текст ошибки, тело ответа или путь URL.

Ту же недавнюю историю можно посмотреть в Агенты → выберите агента → Вебхуки → Недавние доставки. В строках отображаются метка конечной точки и источник URL, использованный в последней попытке. Это операционное состояние, а не неизменяемый журнал аудита: удаление конечной точки также удаляет её строки доставок.

При 404 от n8n сначала убедитесь, что рабочий процесс активен, принимает POST и использует URL вебхука для продакшена, а не тестовый URL. Ошибки 401 или 403 указывают на аутентификацию или проверку подписи; тайм-ауты — на задержки или доступность целевого сервера; ошибки TLS — на цепочку сертификатов, имя хоста или срок действия.

Связанные материалы#