Крајње тачке вебхукова

Управљајте са више 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",
  "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. Приказује недавне покушаје из оба система веб-хукова, укључујући идентификатор позива, порекло URL-а, HTTP статус, број покушаја, категорију неуспеха са листе дозвољених и време следећег поновног покушаја. Никада не враћа садржај догађаја, транскрипт, сачувани текст грешке, тело одговора или путању URL-а.

Исто тако можете видети историју недавних покушаја у Агенти → изаберите агента → Веб-хукови → Недавне испоруке. Редови приказују ознаку крајње тачке и порекло URL-а коришћено у последњем покушају. Ово је оперативно стање, а не непроменљиви дневник ревизије: брисањем крајње тачке бришу се и њени редови испорука.

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

Повезано#