ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Webhooks

Webhook крајње тачке

Управљајте вишеструким webhook 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_idцео број | nullАгент на ког је ова крајња тачка ограничена; null значи за целу организацију
agent_nameстринг | nullНазив ограниченог агента или null за крајњу тачку за целу организацију
secret_hintстрингПрва 4 и последња 4 знака тајне за потписивање са тротачком (a1b2…9f0e) — довољно за упоређивање са тајном коју сте сачували локално, без откривања пуне вредности
paused_atвременска ознака | nullКада је ThunderPhone поставио крајњу тачку на failing. null док је active или disabled
pause_last_errorстрингПоследња грешка испоруке када је крајња тачка паузирана, на пример HTTP 503: Service Unavailable. Празно осим ако је failing
pause_undelivered_countцео број | nullДогађаји који нису испоручени од последње успешне испоруке крајње тачке, пребројани када је паузирана
created_at, updated_atвременска ознака

Важећи типови догађаја

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 са објектом крајње тачке и додатним пољем 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"]
  }'
ПољеТипОпис
labelстринг
urlстринг
eventsниз
statusстрингactive или disabled. Поставите active да бисте поново омогућили крајњу тачку коју је сервер означио као failing
agent_idцео број | nullПоставите ИД агента да бисте ограничили крајњу тачку или null да би била на нивоу целе организације

Враћа 200 OK са ажурираним објектом крајње тачке.


Ротирајте тајну за потписивање

Замените тајну за потписивање крајње тачке, на пример ако је изгубљена или је можда процурела. Можете користити и контролну таблу: отворите крајњу тачку у оквиру Интеграције → Вебхукови (тамо су наведене и крајње тачке на нивоу организације и крајње тачке агента) и изаберите Ротирајте.

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објекатОбјекат крајње тачке са новим 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-а коришћен у последњем покушају. Ово је оперативно стање, а не непроменљиви дневник ревизије: брисање крајње тачке такође брише њене редове испоруке.

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


Повезано