Open in
Крайни точки за уебкуки
Управлявайте множество URL адреси за уебкуки с тайни ключове за всяка крайна точка и филтри за събития.
Системата за уебхукове, базирана на крайни точки, ви позволява да регистрирате множество дестинации за организация, всяка със собствена тайна, собствен статус и собствен абонамент за подмножество от типове събития. Това е препоръчителният модел за всички нови интеграции.
Сравнете с наследения уебхук с един URL, който се поддържа за обратна съвместимост, но поддържа само един 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}/rotate-secret | admin+ | Замяна на тайната за подписване |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Изпращане на подписана тестова доставка |
GET | /v1/developer/webhook-deliveries | admin+ | Преглед на скорошни резултати от доставки на крайни точки и остарели доставки |
Обект на крайна точка
{
"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"
}| Поле | Тип | Описание |
|---|---|---|
id | UUID | Идентификатор на крайната точка |
label | низ | Показвано име, 1–120 знака |
url | низ | HTTPS URL адрес; http://localhost е разрешен за разработка |
events | масив от низове | Типове събития, за които сте абонирани (вижте валидни стойности). Празният масив ви абонира за всички събития с изключение на събитията, изискващи изрично абониране (telephony.turn / web.turn / call.status_changed) |
status | низ | active, disabled (ръчно поставена на пауза) или failing (задава се автоматично, когато доставката изчерпи 24-часовия си график за повторни опити без нито един 2xx отговор) |
agent_id | integer | null | Агентът, до който е ограничена тази крайна точка; null означава за цялата организация |
agent_name | string | null | Името на ограничения агент или null за крайна точка за цялата организация |
secret_hint | низ | Първите 4 и последните 4 знака от тайната за подписване с многоточие (a1b2…9f0e) — достатъчно, за да сверите локално запазената тайна, без да разкривате пълната стойност |
paused_at | timestamp | null | Кога ThunderPhone е задал крайната точка на failing. null, докато е active или disabled |
pause_last_error | низ | Последната грешка при доставка, когато крайната точка е била поставена на пауза, например HTTP 503: Service Unavailable. Празно, освен ако не е failing |
pause_undelivered_count | integer | null | Събития, които не са доставени след последната успешна доставка на крайната точка, преброени при поставянето ѝ на пауза |
created_at, updated_at | timestamp |
Валидни типове събития
events се валидира спрямо този точен набор — стойности извън списъка
връщат 400. Вижте Каталог със събития за структурата на
полезния товар на всеки тип.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(запазено; все още не се изпраща)scheduled.skipped,scheduled.failedcall.graded,call.data_extracted,call.transfer_completed,call.status_changedcampaign.completedissue.reported,issue.escalatedtest-call.completedalert.triggeredphone_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 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"]Полета на заявката
| Поле | Тип | Задължително | Описание |
|---|---|---|---|
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 -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 | string | |
url | string | |
events | array | |
status | string | active или disabled. Задайте active, за да активирате отново крайна точка, която сървърът е маркирал като failing |
agent_id | integer | null | Задайте идентификатор на агент, за да ограничите крайната точка, или null, за да я направите за цялата организация |
Връща 200 OK с актуализирания обект Endpoint.
Сменете тайния ключ за подписване
Заменете тайната за подписване на крайна точка, например ако е била изгубена или може да е изтекла. Можете също да използвате таблото за управление: отворете крайната точка в Интеграции → Уебкуки (там са изброени крайните точки за цялата организация и за агентите) и изберете Завъртане.
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 -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 -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 грешките сочат към веригата на сертификата, името на хоста или срока му на валидност.