ThunderPhone v3 вече е тук.Започнете самостоятелно — от 2 цента/мин.Прочетете съобщението

Webhooks

Крайни точки за уебкуки

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

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

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

Крайни точки

МетодПътИзисквана роляОписание
GET/v1/developer/webhook-endpointsadmin+Извеждане на списък с крайни точки
POST/v1/developer/webhook-endpointsadmin+Създаване на крайна точка
PATCH/v1/developer/webhook-endpoints/{endpoint_id}admin+Актуализиране на етикет / URL / събития / статус
DELETE/v1/developer/webhook-endpoints/{endpoint_id}admin+Изтриване на крайна точка
POST/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secretadmin+Замяна на тайната за подписване
POST/v1/developer/webhook-endpoints/{endpoint_id}/testadmin+Изпращане на подписана тестова доставка
GET/v1/developer/webhook-deliveriesadmin+Преглед на скорошни резултати от доставки на крайни точки и остарели доставки

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

{
  "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"
}
ПолеТипОписание
idUUIDИдентификатор на крайната точка
labelнизПоказвано име, 1–120 знака
urlнизHTTPS URL адрес; http://localhost е разрешен за разработка
eventsмасив от низовеТипове събития, за които сте абонирани (вижте валидни стойности). Празният масив ви абонира за всички събития с изключение на събитията, изискващи изрично абониране (telephony.turn / web.turn / call.status_changed)
statusнизactive, disabled (ръчно поставена на пауза) или failing (задава се автоматично, когато доставката изчерпи 24-часовия си график за повторни опити без нито един 2xx отговор)
agent_idinteger | nullАгентът, до който е ограничена тази крайна точка; null означава за цялата организация
agent_namestring | nullИмето на ограничения агент или null за крайна точка за цялата организация
secret_hintнизПървите 4 и последните 4 знака от тайната за подписване с многоточие (a1b2…9f0e) — достатъчно, за да сверите локално запазената тайна, без да разкривате пълната стойност
paused_attimestamp | nullКога ThunderPhone е задал крайната точка на failing. null, докато е active или disabled
pause_last_errorнизПоследната грешка при доставка, когато крайната точка е била поставена на пауза, например HTTP 503: Service Unavailable. Празно, освен ако не е failing
pause_undelivered_countinteger | nullСъбития, които не са доставени след последната успешна доставка на крайната точка, преброени при поставянето ѝ на пауза
created_at, updated_attimestamp

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

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

  • telephony.incoming, telephony.complete, telephony.tool, telephony.turn
  • web.incoming, web.complete, web.tool, web.turn
  • sms.sent, sms.failed
  • sms.received (запазено; все още не се изпраща)
  • scheduled.skipped, scheduled.failed
  • call.graded, call.data_extracted, call.transfer_completed, call.status_changed
  • campaign.completed
  • issue.reported, issue.escalated
  • test-call.completed
  • alert.triggered
  • phone_number.spam_risk_changed

issue.escalated и phone_number.spam_risk_changed нямат контекст за агент и се доставят само до крайни точки за цялата организация.

voice.ready и voice.failed не могат да бъдат избрани изрично. За да ги получавате, създайте крайна точка за цялата организация с events: []. Празен списък със събития получава всяко поддържано събитие с изключение на telephony.turn, web.turn и call.status_changed, които трябва да бъдат избрани изрично.

Статуси на крайните точки

  • active — доставките протичат нормално.
  • disabled — ръчно поставена на пауза чрез PATCH. Не се изпращат заявки. Ние никога не променяме статуса на крайна точка с disabled; връщането му на active винаги е ваше решение.
  • failing — задава се автоматично, когато доставка до крайната точка изчерпи целия си график за повторни опити (8 опита за 24 часа), без да получи 2xx. Крайна точка с грешка не получава повече трафик. Изпращаме имейл до собствениците и администраторите на вашата организация, когато това се случи, а таблото показва поставената на пауза крайна точка с бутон „Активиране отново“. След като крайната точка бъде поправена, върнете статуса ѝ чрез PATCH на active; доставките, чийто график за повторни опити все още не е изтекъл, се възобновяват оттам, докъдето са стигнали.

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

cURL
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
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
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 / call.status_changed, които изискват изричен абонамент. Трябва да използвате стойностите, изброени във Валидни типове събития; дубликатите се премахват
agent_idцяло число | nullнеОграничете доставянето до агент в тази организация; пропуснете или използвайте null за крайна точка за цялата организация

Връща 201 Created с обекта Endpoint плюс допълнително поле 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
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"]
  }'
ПолеТипОписание
labelstring
urlstring
eventsarray
statusstringactive или disabled. Задайте active, за да активирате отново крайна точка, която сървърът е маркирал като failing
agent_idinteger | nullЗадайте идентификатор на агент, за да ограничите крайната точка, или null, за да я направите за цялата организация

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


Сменете тайния ключ за подписване

Заменете тайната за подписване на крайна точка, например ако е била изгубена или може да е изтекла. Можете също да използвате таблото за управление: отворете крайната точка в Интеграции → Уебкуки (там са изброени крайните точки за цялата организация и за агентите) и изберете Завъртане.

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 '{}'
ПолеТипЗадължителноОписание
include_copiesбулевонеПо подразбиране true. Предоставя новия таен ключ и на другите крайни точки на вашата организация със същия URL адрес и същия текущ таен ключ, като например копия на тази крайна точка при други агенти, така че един получател да продължи да проверява с един таен ключ

Връща 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
ПолеТипОписание
endpointобектОбектът Endpoint с новия си secret_hint
secretнизНовият таен ключ за подписване. Връща се само в този отговор
rotated_endpoint_idsмасив от UUIDВсяка крайна точка, която вече използва новия таен ключ

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

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

cURL
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.

Примерите за завършено обаждане (telephony.complete, web.complete) и call.data_extracted съдържат собствените полета на агента за събиране на данни в extracted_data.fields със стойности заместители, както при реалните му обаждания. За агент, който не събира данни, примерът за завършено обаждане изпраща extracted_data: null, както при реалните му обаждания, а примерът за call.data_extracted има празни fields (реалните обаждания никога не изпращат това събитие за такъв агент). summary на примера е null, когато резюмето на обажданията на агента е изключено. В крайна точка на агент примерът следва този агент; в крайна точка за цялата организация подайте незадължителен agent_id, за да го моделирате по конкретен агент, или го пропуснете за общия пример.


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

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

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

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


Свързани