---
title: "Vituo vya mwisho vya Webhook"
description: "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](/api-reference/organizations#legacy-single-url-webhook),
ambayo imehifadhiwa kwa uoanifu wa nyuma lakini inatumia URL moja pekee kwa
kila shirika.

## Endpointi

| Mbinu | Njia | Jukumu linalohitajika | Maelezo |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Orodhesha endpointi |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Unda endpointi |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Sasisha lebo / URL / matukio / hali |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Futa endpointi |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Tuma uwasilishaji wa majaribio uliotiwa saini |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Kagua matokeo ya hivi karibuni ya uwasilishaji wa endpointi na wa urithi |

## Kitu cha endpoint

```json
{
  "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"
}
```

| 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 mazingira ya uendelezaji |
| `events` | array of string | Aina za matukio yaliyojisajiliwa (tazama [thamani halali](#valid-event-types)). Array tupu inajisajili kwa matukio yote isipokuwa matukio ya kila zamu yanayohitaji kuchaguliwa waziwazi (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (imesitishwa mwenyewe), au `failing` (huwekwa kiotomatiki uwasilishaji unapomaliza ratiba yake ya kujaribu tena ya saa 24 bila hata 2xx moja) |
| `agent_id` | integer \| null | Ejenti ambaye endpoint hii imewekewa upeo kwake; `null` inamaanisha kwa 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 duaradufu (`a1b2…9f0e`) — zinatosha kulinganisha na siri uliyohifadhi ndani ya mazingira yako bila kufichua thamani kamili |
| `created_at`, `updated_at` | timestamp | |

<Note>
  `secret` kamili ya endpoint inarejeshwa **mara moja** wakati wa uundaji na
  haitarejeshwa tena. Ihifadhi kwa usalama — ukiipoteza, futa endpoint
  na uiunde upya.
</Note>

### Aina halali za matukio

`events` inathibitishwa dhidi ya seti hii kamili — thamani zilizo nje ya orodha
zinarejesha `400`. Tazama [Orodha ya matukio](/sw/webhooks/events) 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

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Hurejesha array ya [vitu vya endpoint](#endpoint-object).
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

<CodeGroup>
```bash 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 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"]
```
</CodeGroup>

### Sehemu za ombi

| Sehemu | Aina | Inahitajika | Maelezo |
|-------|------|----------|-------------|
| `label` | string | ndiyo | herufi 1–120 |
| `url` | string | ndiyo | URL ya HTTPS (`http` inaruhusiwa kwa `localhost` / `127.0.0.1` pekee) |
| `events` | array | hapana | Ikiwa tupu/haijajumuishwa, hujisajili kwa matukio yote isipokuwa `telephony.turn` / `web.turn`, ambayo yanahitaji usajili wa wazi. Lazima utumie thamani zilizoorodheshwa katika [Aina halali za matukio](#valid-event-types); nakala rudufu huondolewa |
| `agent_id` | integer \| null | hapana | Weka upeo wa uwasilishaji kwa ejenti katika shirika hili; acha bila kujumuisha au tumia `null` kwa endpoint ya shirika zima |

Hurejesha `201 Created` ikiwa na [kitu cha Endpoint](#endpoint-object) pamoja na
sehemu ya ziada ya kiwango cha juu ya `secret` yenye ufunguo ghafi wa kutia sahihi — 
mfuatano wa hexadecimal wa herufi 48:

```json
{
  "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"
}
```

<Warning>
  `secret` hurejeshwa **wakati wa kuunda pekee**. Majibu ya baadaye ya `GET`
  hujumuisha `secret_hint` pekee. Nakili thamani kamili kwenye meneja wako wa siri
  kabla ya kuondoa jibu.
</Warning>

---

## Sasisha endpoint

<CodeGroup>
```bash 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"]
  }'
```
</CodeGroup>

| Sehemu | Aina | Maelezo |
|-------|------|-------------|
| `label` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` au `disabled`. Weka `active` ili kuwezesha tena endpoint ambayo seva imeweka alama ya `failing` |
| `agent_id` | integer \| null | Weka kitambulisho cha ejenti ili kuweka upeo wa endpoint, au `null` ili kuifanya iwe ya shirika zima |

Hurejesha `200 OK` ikiwa na [kitu cha Endpoint](#endpoint-object) 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`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Kituo lengwa hupokea bahasha kama hii:

```json
{
  "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:

```json
{
  "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`.

```bash
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](#valid-event-types).
Kutoijumuisha huhifadhi tabia ya jumla ya `webhook.test`.

---

## Futa kituo lengwa

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

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`](/api-reference/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

<CardGroup cols={2}>
  <Card title="Katalogi ya matukio" icon="list" href="/sw/webhooks/events">
    Orodha kamili ya thamani za `events` unazoweza kujisajili kupokea.
  </Card>
  <Card title="Muhtasari wa webhook" icon="bolt" href="/sw/webhooks/overview">
    Uthibitishaji wa sahihi na mantiki ya uwasilishaji.
  </Card>
</CardGroup>