# Kupata matokeo ya uthibitishaji kwa webhooks

Source: https://help.didit.me/sw/integration/webhooks-basics
Updated: 2026-10-12

Didit hukutumii barua pepe uthibitishaji unapobadilisha hali - weka webhook ili backend yako isikie mara tu inapotokea, na thibitisha saini kabla ya kuiamini.

Webhook ni ombi la HTTP ambalo Didit hutuma kwenye URL yako wakati kitu
kinabadilika. Ongeza lengo chini ya **Wasanidi → Webhooks**, jisajili kwa matukio
unayotaka - hakuna **wildcard**, orodhesha kila moja - hifadhi siri ya kusaini, na
thibitisha saini kabla ya kuchakata chochote.

[Video: Muhtasari wa webhooks - Didit Academy](https://www.youtube.com/watch?v=fX03-WEu_EI&t=192)

Didit hakutumii barua pepe wakati kikao kinaposogea hadi **In Review** au **Declined**. Ili kujua wakati hali inabadilika, bila kupakua upya console, weka webhook - URL kwenye seva yako ambayo Didit hutuma sasisho kwa njia ya kiotomatiki.

Webhooks ndiyo muundo wa muunganisho **unaopendekezwa**. Kufuatilia endpoint ya uamuzi (polling) kunafanya kazi kama hifadhi ya nyuma, lakini ni polepole, kunatumia maombi zaidi, na kunapoteza matukio ambayo hutolewa tu na webhook - marekebisho ya data yaliyofanywa na mkaguzi, mabadiliko ya hali ya miamala, na mabadiliko ya kiwango cha entity.

## Kuweka moja

1. **Wasanidi → Webhooks**

   Fungua programu na mazingira sahihi ya Live au Sandbox, kisha Wasanidi na Webhooks.

2. **Ongeza endpoint**

   Bonyeza Ongeza endpoint, weka URL ya HTTPS na jina, kisha chagua matukio. Tumia toleo linalopendekezwa la v3 isipokuwa unatunza muunganisho wa zamani. Kagua na uthibitishe.

3. **Hifadhi siri ya kusaini**

   Kila endpoint ina siri yake ya sahihi iliyofichwa. Bonyeza Onyesha na uthibitishe utambulisho; hufichwa tena ndani ya sekunde 60. Ihifadhi kwenye mipangilio ya seva. Wasiliana na usaidizi ikiwa kitufe kimezimwa. [Wasanidi → Webhooks](https://docs.didit.me/integration/webhooks#signature-verification).

4. **Tuma tukio la majaribio**

   Tuma tukio la majaribio lenye sahihi ili kukagua endpoint, sahihi na uchakataji bila uthibitishaji halisi.

![Malengo ya webhook katika console ya Didit yakiwa na matukio yaliyosajiliwa na historia ya utoaji](https://help.didit.me/screenshots/webhooks-light.webp)

*Kila lengo lina matukio yake yaliyosajiliwa, siri yake ya kusaini, na kumbukumbu yake ya utoaji.*

## Matukio unayoweza kujisajili

Hakuna **wildcard** - orodhesha kila kundi la matukio unalotaka. Kuyagawa kwenye malengo kadhaa ni sawa na mara nyingi ni safi zaidi.

| Tukio | Huzindua wakati |
|---|---|
| `status.updated` | Hali ya kikao cha KYC au KYB inabadilika. Lile ambalo karibu kwa hakika unalitaka |
| `data.updated` | Data ya uthibitishaji inahaririwa baada ya kuundwa - mkaguzi anasahihisha sehemu |
| `user.status.updated` | Mtumiaji aliyeunganishwa anasogea kati ya ACTIVE, FLAGGED na BLOCKED |
| `user.data.updated` | Wasifu, kihesabu, au vitambulisho vya mtumiaji aliyeunganishwa vinabadilika |
| `business.status.updated` | Biashara iliyoungani inabadilisha hali |
| `business.data.updated` | Data ya biashara iliyoungani inabadilika |
| `transaction.created` | Muamala unaundwa na uamuzi wake wa awali uko tayari |
| `transaction.status.updated` | Hali ya muamala inabadilika baadaye |
| `travel_rule.status.updated` | Hali ya kubadilishana kwa Travel Rule inabadilika |

> **Note:** Hakuna `session.status.updated` au `kyc.completed`. Ukisajili jina lisilo katika
> orodha hii, hutapokea chochote - na itaonekana kama hitilafu ya utoaji hasa. Angalia
> jina kwanza.

## Kile endpoint yako inapaswa kufanya

- **Thibitisha saini kabla ya kitu kingine chochote.** Fanya HMAC kwenye maudhui **ghafi** ya ombi - kamwe si toleo lililorudiwa kuandikwa la JSON iliyochambuliwa, kwa sababu kuandika upya kunabadilisha bytes na saini haitalingana. Tumia ulinganishaji wa muda thabiti.
- **Rudisha 2xx haraka.** Fanya kazi nzito kwa njia isiyosubiri (asynchronous), baada ya kujibu.
- **Kuwa idempotent.** Tumia kama ufunguo id ya tukio, au id ya kikao pamoja na hali pamoja na aina ya webhook. Marudio na nakala hutokea.
- **Shughulikia kila hali unayojali**, ikiwa ni pamoja na zile zinazofika muda mrefu baada ya uandikishaji - kikao kilichoidhinishwa kinaweza baadaye kusogea hadi In Review kupitia [ufuatiliaji endelevu wa AML](https://help.didit.me/sw/aml-screening/ongoing-monitoring).
- **HTTPS pekee.** Endpoints za HTTP wazi hazitumiki.

## Marudio

Kwa jibu la 5xx au 404, Didit hujaribu tena mara mbili, baada ya takribani dakika moja kisha nne. Muda wa sekunde 5 ukiisha au muunganisho ukishindwa, hakuna jaribio la kiotomatiki. Baada ya kurekebisha, tumia Tuma tena kwenye Uwasilishaji. Kushindwa kwa mwisho huleta arifa.

> **Warning:** Usidhani kila webhook itafika. Baada ya hitilafu, tuma tena au omba uamuzi wa kila kipindi ambacho hujapokea matokeo yake.

## Nyuma ya firewall au WAF

Didit hutuma kutoka IP tuli **18.203.201.92** ikiwa na user agent ya `DiditWebhook/2.0`. Ikiwa ukingo wako unazuia wateja wasiojulikana - msimamo wa chaguo-msingi wa Cloudflare, kwa mfano - ruhusu IP hiyo kwa hostname inayopokea, au utoaji utashindwa kabla ya kufika kwenye msimbo wako.

## Bado huna backend?

Bado unaweza kufuatilia matokeo kwa mkono kwenye sehemu ya **Verifications** ya console wakati unajenga moja, au tumia [kiungo cha uthibitishaji kisichohitaji msimbo](https://help.didit.me/sw/integration/integration-options) kwa muda huo.

## Hatua zinazofuata

- Wakati webhook haifiki: [wakati webhook haifiki kabisa](https://help.didit.me/sw/integration/webhook-troubleshooting)
- Elewa maana ya kila hali mara inapofika: [maana ya kila hali ya kikao](https://help.didit.me/sw/verification-sessions/session-statuses)
- Rejea kamili ya kiufundi, ikiwa ni pamoja na mifano ya msimbo ya uthibitishaji wa saini: [Webhooks](https://docs.didit.me/integration/webhooks)