Open in
Webhook крајње тачке
Управљајте вишеструким webhook 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 | цео број | 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.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 са објектом крајње тачке и додатним
пољем 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 | стринг | |
url | стринг | |
events | низ | |
status | стринг | active или disabled. Поставите active да бисте поново омогућили крајњу тачку коју је сервер означио као failing |
agent_id | цео број | null | Поставите ИД агента да бисте ограничили крајњу тачку или null да би била на нивоу целе организације |
Враћа 200 OK са ажурираним објектом крајње тачке.
Ротирајте тајну за потписивање
Замените тајну за потписивање крајње тачке, на пример ако је изгубљена или је можда процурела. Можете користити и контролну таблу: отворите крајњу тачку у оквиру Интеграције → Вебхукови (тамо су наведене и крајње тачке на нивоу организације и крајње тачке агента) и изаберите Ротирајте.
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 -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-а коришћен у последњем покушају. Ово је оперативно стање, а не непроменљиви дневник ревизије: брисање крајње тачке такође брише њене редове испоруке.
За n8n 404, најпре потврдите да је радни ток активан, прихвата POST и користи
продукциони URL веб-хука уместо тест URL-а. 401 или 403 указује на
аутентификацију или валидацију потписа; истек времена указује на кашњење
или доступност одредишта; TLS грешке указују на ланац сертификата, име хоста или истек.