Open in
Vituo vya Mwisho vya Webhook
Dhibiti URL nyingi za webhook zenye siri za kila kituo cha mwisho na vichujio vya matukio.
Mfumo wa webhook unaotegemea endpoint hukuruhusu kusajili maeneo mengi ya kutuma kwa kila shirika, kila moja likiwa na siri yake, hali yake, na usajili wake kwa sehemu ya aina za matukio. Huu ndio muundo unaopendekezwa kwa miunganisho yote mipya.
Linganisha na webhook ya zamani ya URL moja, ambayo imehifadhiwa kwa uoanifu wa nyuma lakini inasaidia URL moja tu kwa kila shirika.
Endpoint
| Mbinu | Njia | Jukumu linalohitajika | Maelezo |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | Orodhesha endpoints |
POST | /v1/developer/webhook-endpoints | admin+ | Unda endpoint |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Sasisha lebo / URL / matukio / hali |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | Futa endpoint |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | Badilisha siri ya kutia sahihi |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | Tuma uwasilishaji wa majaribio uliotiwa sahihi |
GET | /v1/developer/webhook-deliveries | admin+ | Kagua matokeo ya hivi karibuni ya uwasilishaji wa endpoint na wa urithi |
Kitu cha endpoint
{
"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"
}| Sehemu | Aina | Maelezo |
|---|---|---|
id | UUID | Kitambulisho cha endpoint |
label | string | Jina la kuonyesha, herufi 1–120 |
url | string | URL ya HTTPS; http://localhost inaruhusiwa kwa maendeleo |
events | array of string | Aina za matukio yaliyosajiliwa (tazama thamani halali). Mkusanyiko tupu hujisajili kwa matukio yote isipokuwa matukio yanayohitaji kutajwa wazi (telephony.turn / web.turn / call.status_changed) |
status | string | active, disabled (imesitishwa mwenyewe), au failing (huwekwa kiotomatiki wakati uwasilishaji unamaliza ratiba yake ya kujaribu tena ya saa 24 bila jibu hata moja la 2xx) |
agent_id | integer | null | Ejenti ambayo endpoint hii imewekewa upeo; null inamaanisha shirika lote |
agent_name | string | null | Jina la ejenti aliyewekewa upeo, au null kwa endpoint ya shirika lote |
secret_hint | string | Herufi 4 za kwanza na 4 za mwisho za siri ya kutia sahihi zenye alama ya duaradufu (a1b2…9f0e) — zinatosha kulinganisha na siri uliyohifadhi ndani ya mfumo wako bila kufichua thamani kamili |
paused_at | timestamp | null | Wakati ThunderPhone iliweka endpoint katika hali ya failing. null ikiwa iko katika hali ya active au disabled |
pause_last_error | string | Hitilafu ya mwisho ya uwasilishaji wakati endpoint ilisimamishwa, kwa mfano HTTP 503: Service Unavailable. Tupu isipokuwa ikiwa ni failing |
pause_undelivered_count | integer | null | Matukio ambayo hayakuwasilishwa tangu uwasilishaji wa mwisho uliofaulu wa endpoint, yakihesabiwa iliposimamishwa |
created_at, updated_at | timestamp |
Aina halali za matukio
events huthibitishwa dhidi ya seti hii kamili — thamani zilizo nje ya orodha
hurudisha 400. Tazama orodha ya Matukio kwa muundo wa
payload wa kila aina.
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(imehifadhiwa; bado haijatolewa)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 na phone_number.spam_risk_changed hazina muktadha wa ejenti na
hutumwa tu kwa endpoint za shirika zima.
voice.ready na voice.failed haziwezi kuchaguliwa moja kwa moja. Ili kuzipokea,
unda endpoint ya shirika lote yenye events: []. Orodha tupu ya matukio hupokea kila tukio linalotumika isipokuwa telephony.turn, web.turn na
call.status_changed, ambazo lazima zichaguliwe moja kwa moja.
Hali za endpoint
active— uwasilishaji unaendelea kama kawaida.disabled— imesitishwa mwenyewe kupitiaPATCH. Hakuna maombi yanayotumwa. Hatuwahi kubadilisha hali ya endpoint yadisabled; kuirejesha kuwaactiveni uamuzi wako kila wakati.failing— huwekwa kiotomatiki wakati uwasilishaji kwa endpoint unatumia ratiba yake yote ya kujaribu tena (majaribio 8 ndani ya saa 24) bila kupata 2xx yoyote. Endpoint yenye hali ya failing haipokei trafiki zaidi. Tunatuma barua pepe kwa wamiliki na wasimamizi wa shirika lako hili linapotokea, na dashibodi huonyesha endpoint iliyositishwa yenye kitufe cha Kuamilisha tena. Endpoint ikisharekebishwa,PATCHhali yake irudi kuwaactive; uwasilishaji ambao ratiba yake ya kujaribu tena haijaisha bado unaendelea kutoka ulipoishia.
Orodhesha endpoint
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Hurejesha mkusanyiko wa vitu vya Endpoint.
Pitisha ?agent_id=42 ili kurejesha endpoint zilizowekewa ukomo kwa ejenti huyo pekee.
Endpoint zilizowekewa ukomo kwa ejenti
Endpoint za shirika lote hupokea kila tukio linalolingana. Endpoint yenye
agent_id hupokea tu matukio yanayolingana ya simu zinazoshughulikiwa na ejenti
huyo; matukio yasiyo na muktadha wa ejenti, kama alert.triggered, hayawafikii.
Unaweza pia kuunda na kusimamia endpoint hizi kutoka sehemu ya
Webhook katika kijenzi cha ejenti.
Unda kituo cha mwisho
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"]Sehemu za ombi
| Sehemu | Aina | Inahitajika | Maelezo |
|---|---|---|---|
label | mfuatano | ndiyo | herufi 1–120 |
url | mfuatano | ndiyo | URL ya HTTPS (http inaruhusiwa tu kwa localhost / 127.0.0.1) |
events | mkusanyiko | hapana | Ikiwa tupu/haijajumuishwa, husajili kwa matukio yote isipokuwa telephony.turn / web.turn / call.status_changed, ambayo yanahitaji usajili wa wazi. Lazima utumie thamani zilizoorodheshwa katika Aina halali za matukio; nakala rudufu huondolewa |
agent_id | nambari kamili | null | hapana | Elekeza uwasilishaji kwa ejenti katika shirika hili; acha au tumia null kwa endpoint ya shirika zima |
Hurejesha 201 Created pamoja na kitu cha Endpoint kilichoongezwa
sehemu ya kiwango cha juu ya secret iliyo na ufunguo halisi wa kutia saini —
mfuatano wa heksadesimali wa herufi 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"
}Sasisha kituo cha mwisho
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"]
}'| Sehemu | Aina | Maelezo |
|---|---|---|
label | mfuatano | |
url | mfuatano | |
events | orodha | |
status | mfuatano | active au disabled. Weka active ili kuwezesha tena kituo cha mwisho ambacho seva iliweka alama failing |
agent_id | nambari kamili | null | Weka kitambulisho cha ejenti ili kuelekeza kituo cha mwisho, au null ili kiwe cha shirika zima |
Hurejesha 200 OK pamoja na kitu cha Endpoint kilichosasishwa.
Badilisha secret ya kutia sahihi
Badilisha siri ya kutia sahihi ya kituo cha mwisho, kwa mfano ikiwa ilipotea au huenda imevuja. Unaweza pia kutumia dashibodi: fungua kituo cha mwisho chini ya Miunganisho → Webhooks (vituo vya mwisho vya shirika zima na vya ejenti vyote vimeorodheshwa hapo) kisha uchague Zungusha.
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 '{}'| Sehemu | Aina | Inahitajika | Maelezo |
|---|---|---|---|
include_copies | boolean | hapana | Chaguo-msingi ni true. Pia hutoa secret mpya kwa endpointi nyingine za shirika lako zilizo na URL sawa na secret ya sasa sawa, kama vile nakala za endpoint hii kwenye ejenti wengine, ili kipokezi kimoja kiendelee kuthibitisha kwa secret moja |
Hurejesha 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| Sehemu | Aina | Maelezo |
|---|---|---|
endpoint | object | Kitu cha Endpoint chenye secret_hint yake mpya |
secret | string | Secret mpya ya kutia sahihi. Hurejeshwa katika jibu hili pekee |
rotated_endpoint_ids | orodha ya UUID | Kila endpoint ambayo sasa inatumia secret mpya |
Tuma uwasilishaji wa majaribio
Tuma tukio bandia la webhook.test kwenye endpoint moja kwa kutumia mfumo wa kawaida wa
uwasilishaji, ikijumuisha usanifishaji wa kikanoni wa JSON, header zote mbili za
sahihi, kurekodi uwasilishaji, na ufuatiliaji wa majaribio ya kurudia.
Jaribio linalenga endpoint iliyochaguliwa bila kujali kichujio chake cha events.
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Endpoint inapokea bahasha kama hii:
{
"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 inarudisha 200 OK baada ya jaribio la kwanza, hata kama lengwa
linarudisha hitilafu. Kagua success, status, response_code, na error
ili kuona matokeo ya uwasilishaji:
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}webhook.test ni bandia na haiwezi kuongezwa kwenye usajili wa events
wa endpoint. Jaribio la kwanza likishindwa, ThunderPhone hulijaribu tena mara moja takriban
dakika moja baadaye kisha husimama; uwasilishaji huonyesha status: "failed"
chini ya Uwasilishaji wa utatuzi. Uwasilishaji wa majaribio hauwahi kuweka
endpoint katika hali ya failing.
Ili kusanidi kichochezi dhidi ya muundo wa tukio halisi, pitisha event_type
ya hiari. Uwasilishaji bado ni bandia na una "sample": true; sampuli zinazohusiana
na simu hutumia call_id: 0 na 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 hukubali thamani yoyote kutoka Aina halali za matukio.
Kuiacha huhifadhi tabia ya jumla ya webhook.test.
Sampuli za simu iliyokamilika (telephony.complete, web.complete) na call.data_extracted
hubeba sehemu za data ambazo ejenti yenyewe inapaswa kukusanya chini ya
extracted_data.fields, zikiwa na thamani za kishikilia nafasi, kama simu zake halisi zinavyofanya. Kwa
ejenti isiyokusanya data, sampuli ya simu iliyokamilika hutuma
extracted_data: null, kama simu zake halisi zinavyofanya, na sampuli ya call.data_extracted
ina fields tupu (simu halisi hazitumi tukio hilo kwa ejenti kama hiyo).
summary ya sampuli ni null wakati muhtasari wa simu wa ejenti umezimwa. Kwenye
endpoint ya ejenti, sampuli hufuata ejenti huyo; kwenye endpoint ya shirika zima,
pitisha agent_id ya hiari ili kuiunda kulingana na ejenti mmoja, au iache ili kupata sampuli ya jumla.
Futa endpoint
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Hurejesha 204 No Content. Uwasilishaji kwa URL husimama mara moja;
majaribio ya kurudia yanayoendelea huachwa.
Tatua uwasilishaji
Kabla ya kuhitimisha kuwa webhook haikutumwa, kagua
GET /v1/developer/webhook-deliveries.
Inaonyesha majaribio ya hivi karibuni kutoka mifumo yote miwili ya webhook, ikijumuisha kitambulisho cha simu,
asili ya URL, hali ya HTTP, idadi ya majaribio, aina ya hitilafu iliyoruhusiwa, na muda wa
jaribio linalofuata. Haiwahi kurudisha payload ya tukio, transkripti, maandishi ya hitilafu yaliyohifadhiwa,
mwili wa jibu, au njia ya URL.
Unaweza pia kuona historia hiyo hiyo ya hivi karibuni katika Ejenti → chagua ejenti → Webhooks → Uwasilishaji wa hivi karibuni. Safu zinaonyesha lebo ya endpoint na asili ya URL iliyotumiwa na jaribio la mwisho zaidi. Hii ni hali ya kiutendaji badala ya kumbukumbu ya ukaguzi isiyobadilika: kufuta endpoint pia hufuta safu zake za uwasilishaji.
Kwa 404 ya n8n, kwanza thibitisha kuwa workflow inatumika, inakubali POST, na inatumia
URL ya webhook ya uzalishaji badala ya URL ya majaribio. 401 au 403 huashiria
uthibitishaji au uhakiki wa sahihi; muda kuisha huashiria ucheleweshaji
au upatikanaji wa lengwa; hitilafu za TLS huashiria mnyororo wa cheti, jina la mpangishaji, au muda wa kuisha.