Vituo vya mwisho vya Webhook

Dhibiti URL nyingi za webhook kwa siri za kila kituo cha mwisho na vichujio vya matukio.

Mfumo wa webhook unaotegemea endpointi hukuruhusu kusajili maeneo lengwa mengi kwa kila shirika, kila moja likiwa na siri yake, hali yake, na usajili wake kwa kikundi kidogo cha aina za matukio. Huu ndio muundo unaopendekezwa kwa miunganisho yote mipya.

Linganisha na webhook ya urithi yenye URL moja, ambayo imehifadhiwa kwa uoanifu wa nyuma lakini inatumia URL moja pekee kwa kila shirika.

Endpointi#

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",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Aina halali za matukio#

events inathibitishwa dhidi ya seti hii kamili — thamani zilizo nje ya orodha zinarejesha 400. Tazama Orodha ya matukio kwa muundo wa payload wa kila aina.

• 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 haina muktadha wa ejenti na huwasilishwa kwa endpoint za shirika lote pekee.

voice.ready na voice.failed haziwezi kuchaguliwa waziwazi. Ili kuzipokea, unda endpoint ya shirika lote yenye events: []. Orodha tupu ya matukio hupokea kila tukio linalotumika isipokuwa telephony.turn na web.turn, ambazo lazima zichaguliwe waziwazi.

Hali za endpoint#

• active — uwasilishaji unaendelea kama kawaida.
• disabled — imesitishwa mwenyewe kupitia PATCH. Hakuna maombi yanayotumwa. Hatuwahi kubadilisha hali ya endpoint ya disabled; kuirejesha kuwa active ni uamuzi wako kila wakati.
• failing — huwekwa kiotomatiki uwasilishaji kwa endpoint unapomaliza ratiba yake yote ya kujaribu tena (majaribio 8 ndani ya saa 24) bila kamwe kupata 2xx. Endpoint yenye hitilafu haipokei trafiki zaidi. Endpoint ikirekebishwa, tumia PATCH kubadilisha hali yake kuwa active; uwasilishaji ambao ratiba yake ya kujaribu tena haijaisha bado huendelea kutoka ulipoishia.

Orodhesha endpoint#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Hurejesha array ya vitu vya endpoint. Tuma ?agent_id=42 ili kurejesha endpoint zilizowekewa upeo kwa ejenti huyo pekee.

Endpoint zilizowekewa upeo kwa ejenti#

Endpoint za shirika lote hupokea kila tukio linalolingana. Endpoint yenye agent_id hupokea matukio yanayolingana tu ya simu zinazoshughulikiwa na ejenti huyo; matukio yasiyo na muktadha wa ejenti, kama alert.triggered, hayaiwafikii. Unaweza pia kuunda na kusimamia endpoint hizi kutoka sehemu ya Webhook katika kijenzi cha ejenti.

Unda endpoint#

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#

Hurejesha 201 Created ikiwa na kitu cha Endpoint pamoja na sehemu ya ziada ya kiwango cha juu ya secret yenye ufunguo ghafi wa kutia sahihi — mfuatano wa hexadecimal 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 endpoint#

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"]
  }'

Hurejesha 200 OK ikiwa na kitu cha Endpoint kilichosasishwa.

Tuma uwasilishaji wa majaribio#

Tuma tukio bandia la webhook.test kwenye kituo kimoja lengwa kwa kutumia njia ya kawaida ya uwasilishaji, ikijumuisha usanifishaji kanoniki wa JSON, X-ThunderPhone-Signature, kurekodi uwasilishaji, na ufuatiliaji wa majaribio ya kurudia. Jaribio linalenga kituo lengwa kilichochaguliwa 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"

Kituo lengwa hupokea 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 hurejesha 200 OK baada ya jaribio la kwanza, hata kama lengwa linarejesha 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 ya bandia na haiwezi kuongezwa kwenye usajili wa events wa kituo lengwa. Jaribio la kwanza likishindwa, uwasilishaji hufuata ratiba ileile ya majaribio ya kurudia kama uwasilishaji wa kawaida wa matukio.

Ili kusanidi kichochezi dhidi ya muundo halisi wa tukio, pitisha event_type ya hiari. Uwasilishaji bado ni wa 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 kwenye Aina halali za matukio. Kutoijumuisha huhifadhi tabia ya jumla ya webhook.test.

Futa kituo lengwa#

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 kwenye URL husimama mara moja; majaribio ya kurudia yanayoendelea huachwa.

Tatua hitilafu za uwasilishaji#

Kabla ya kuhitimisha kuwa webhook haikutumwa, kagua GET /v1/developer/webhook-deliveries. Inaonyesha majaribio ya hivi karibuni kutoka kwenye mifumo yote miwili ya webhook, ikijumuisha kitambulisho cha simu, asili ya URL, hali ya HTTP, idadi ya majaribio, aina ya hitilafu iliyoidhinishwa, na muda wa jaribio linalofuata. Hairejeshi kamwe mzigo wa data wa tukio, nakala ya mazungumzo, maandishi ya hitilafu yaliyohifadhiwa, mwili wa jibu, au njia ya URL.

Unaweza pia kuona historia hiyo hiyo ya hivi karibuni katika Ejenti → chagua ejenti → Webhook → Uwasilishaji wa hivi karibuni. Safu zinaonyesha lebo ya kituo lengwa na asili ya URL iliyotumiwa na jaribio la hivi karibuni. Hii ni hali ya uendeshaji badala ya kumbukumbu ya ukaguzi isiyobadilika: kufuta kituo lengwa hufuta pia safu zake za uwasilishaji.

Kwa 404 ya n8n, kwanza thibitisha kuwa mtiririko wa kazi unatumika, unakubali POST, na unatumia URL ya webhook ya uzalishaji badala ya URL ya majaribio. 401 au 403 huashiria uthibitishaji au uthibitishaji wa sahihi; muda kuisha huashiria ucheleweshaji au upatikanaji wa lengwa; hitilafu za TLS huashiria mnyororo wa cheti, jina la mwenyeji, au kuisha kwa muda wake.

Yanayohusiana#