Webhook ni Nini? Jinsi Programu Zinavyotaarifiana

Webhook ni ujumbe wa kiotomatiki ambao huduma moja hutuma kwenye programu yako mara tu kitu kinapotokea. Malipo ya mteja yanapofanikiwa, Stripe hutuma webhook kwenye anwani ndani ya programu yako ikisema "malipo yamefanikiwa, haya ni maelezo", na programu yako inajibu — inaweka oda kuwa imelipwa, inatuma risiti, inafungua akaunti. Kwa kifupi: API ni programu yako ikiuliza huduma nyingine swali; webhook ni huduma nyingine ikiita programu yako kukuambia kitu.

Kwa nini ni muhimu unapojenga na AI

Programu yako inapokubali malipo, kupokea fomu kutoka zana nyingine, au kuunganishwa na huduma kama GitHub, Shopify au kalenda, utakutana na webhooks. Mara nyingi ndiyo njia sahihi ya kujua kwamba jambo limetokea — lakini pia ndipo programu zilizojengwa kwa AI mara nyingi huwa na makosa madogo:

• Mwisho wa mawasiliano unakubali ombi lolote, kwa hiyo mtu yeyote anaweza kutuma tukio la uongo la "malipo yamefanikiwa".
• Programu inatoa ufikiaji kwenye ukurasa wa kurudishwa wa malipo badala ya webhook, kwa hiyo watu wanaofunga kichupo mapema hawapati walichonunua, na watu wanaopata URL ya mafanikio wanapata bure.
• Tukio hilohilo linafika mara mbili na mteja anapata oda mbili au barua pepe mbili.

Kujua jinsi webhooks zinavyofanya kazi kunakuwezesha kuomba kinga hizi mapema.

Mfano wa kila siku: ujumbe wa kifurushi

Unaweza kujua kama kifurushi chako kimefika kwa njia mbili. Unaweza kutembea mlango wa mbele kila dakika kumi kukagua (hiyo ni polling — programu yako ikiita API tena na tena kuuliza "kuna chochote kipya?"). Au msafirishaji anaweza kukutumia ujumbe kifurushi kimefika (hiyo ni webhook).

Ujumbe ni bora zaidi — mradi unaweza kuuamini. Kama mtu yeyote angeweza kukutumia ujumbe wa "kifurushi kimefika", ungetaka njia ya kujua kama umetoka kweli kwa msafirishaji. Na kama simu yako ilikuwa imezimwa ujumbe ulipofika, ungetaka msafirishaji ajaribu tena baadaye. Mambo hayo mawili — uthibitishaji na kujaribu upya — ndiyo yanayofanya webhooks ziwe ngumu.

Webhook inavyofanya kazi, hatua kwa hatua

1. Unaunda mwisho wa mawasiliano (endpoint) kwenye backend ya programu yako: URL kama https://yourapp.com/webhooks/stripe inayokubali maombi ya POST.
2. Unasajili URL hiyo kwa mtoa huduma na kuchagua matukio unayotaka (kwa mfano, "checkout imekamilika" na "usajili umeghairiwa").
3. Mtoa huduma anakupa siri ya kusaini. Unaihifadhi kama siri kwenye seva yako — angalia variables za mazingira na siri.
4. Tukio linatokea. Mtoa huduma anatuma ombi la HTTP kwenye URL yako lenye mwili wa JSON unaoeleza tukio, pamoja na kichwa cha sahihi.
5. Programu yako inahakiki sahihi, inarekodi kitambulisho cha tukio, inajibu kwa msimbo wa mafanikio (200) haraka, kisha inafanya kazi.
6. Ikiwa programu yako haijibu kwa mafanikio, watoa huduma wengi hujaribu tena baadaye.

Sahihi

Sahihi inathibitisha kwamba ombi limetoka kwa mtoa huduma na halijabadilishwa. Stripe, kwa mfano, huhesabu HMAC (aina ya alama ya kidijitali yenye ufunguo) kwa kutumia SHA-256 juu ya mwili wa ombi na muhuri wa muda, ukitumia siri ya kusaini, na kuituma kwenye kichwa cha Stripe-Signature. Programu yako inafanya hesabu hiyo hiyo kwa nakala yake ya siri; kama matokeo yanalingana, ombi ni halisi. Kwa kuwa muhuri wa muda pia umesainiwa, unaweza kukataa maombi ya zamani ambayo mtu alirekodi na kuyarudia baadaye — maktaba za Stripe zina uvumilivu wa dakika tano kwa chaguo-msingi, kulingana na nyaraka zake kufikia Septemba 2026.

Maelezo moja ya kivitendo: sahihi inahesabiwa juu ya mwili ghafi wa ombi. Ikiwa fremu yako inachambua na kupanga upya JSON kabla ya kuhakiki, ukaguzi unashindwa. Hii ni hitilafu ya kawaida sana.

Majaribio upya, marudio na mpangilio

Watoa huduma wanatofautiana, kwa hiyo angalia nyaraka za kila mmoja. Kufikia Septemba 2026:

Nyaraka za Stripe pia zinasema kwamba matukio hayahakikishiwi kufika kwa mpangilio yalivyotokea, na kwamba tukio hilohilo linaweza mara chache kufika zaidi ya mara moja, kwa hiyo linapendekeza ufuatilie vitambulisho vya matukio.

Somo la jumla linasimama kwa mtoa huduma yeyote: matukio yanaweza kufika yamechelewa, mara zaidi ya moja na bila mpangilio. Kishughulikiaji chako kinapaswa kuwa idempotent — kuchakata tukio lilelile mara mbili kuwe na athari sawa na kulichakata mara moja.

Mfano kamili: kufungua kozi iliyolipiwa

Unauza kozi mtandaoni. Mwanafunzi anabonyeza Nunua, analipa kwenye ukurasa wa malipo wa Stripe, na anarudishwa kwenye tovuti yako.

Njia dhaifu: ukurasa wa "asante" unafungua kozi. Mwanafunzi akifunga kivinjari wakati wa kurudishwa, amelipa lakini hana ufikiaji. Mtu akikisia URL ya ukurasa wa asante, anapata ufikiaji bila kulipa.

Njia ya webhook:

1. Stripe inapothibitisha malipo, inatuma tukio la checkout.session.completed kwenye /webhooks/stripe.
2. Backend yako inahakiki sahihi kwa siri ya kusaini. Ikishindwa, inajibu 400 na haifanyi chochote.
3. Inakagua kama kitambulisho cha tukio hilo kimeshachakatwa. Kama ndiyo, inajibu 200 na kusimama.
4. Inahifadhi kitambulisho cha tukio, inajibu 200, kisha inampa mwanafunzi ufikiaji na kutuma barua pepe ya karibu.
5. Ukurasa wa "asante" unasema tu "Malipo yamepokelewa — kozi yako itaonekana hivi punde" na kukagua hali ya ufikiaji ya mwanafunzi.

Baadaye, ikiwa usajili umeghairiwa au kadi imeshindwa, matukio mengine ya webhook yanaiambia programu yako kuondoa au kusimamisha ufikiaji. Hivyo ndivyo bidhaa za usajili zinavyobaki sambamba na malipo — angalia SaaS ni nini na jinsi ya kuongeza malipo kwenye programu yako.

Maneno muhimu

• Endpoint: URL kwenye programu yako inayopokea webhooks.
• Tukio / payload: kilichotokea, na data inayokieleza (kwa kawaida JSON).
• Siri ya kusaini: siri inayoshirikiwa inayotumika kuhakiki sahihi.
• Idempotent: salama kuendeshwa zaidi ya mara moja kwa matokeo yale yale.
• Polling: kuuliza API mara kwa mara kwa mabadiliko badala ya kusubiri webhook.
• Tunnel: zana inayotoa laptop URL ya umma ya muda ili webhooks zifike wakati wa maendeleo.

Makosa ya kawaida na dhana potofu

• Kutohakiki sahihi. URL ya mwisho wa mawasiliano si siri. Uthibitishaji ndio unaofanya ombi liaminike.
• Kufanya kazi nzito kabla ya kujibu. Kutuma barua pepe au kuzalisha PDF kabla ya kujibu kunaweza kusababisha muda kuisha, ambao husababisha majaribio upya, ambayo husababisha marudio.
• Kudhani mara moja tu, kwa mpangilio. Rekodi vitambulisho vya matukio na usitegemee mpangilio wa kufika.
• Kutumia URL ya hakiki. Webhooks zinahitaji anwani thabiti ya umma. Hakiki za faragha na localhost hazifikiki kutoka intaneti; tumia URL yako iliyochapishwa (au tunnel wakati wa kujaribu).
• Kuchanganya siri za majaribio na za moja kwa moja. Watoa huduma mara nyingi hutoa siri tofauti za kusaini kwa hali ya majaribio na ya moja kwa moja. Hifadhi zote mbili na utumie sahihi.
• Kuamini payload bila kukagua kwa maamuzi makubwa. Kwa vitendo vyenye hatari kubwa, ni busara kuchukua hali ya karibuni kutoka kwenye API ya mtoa huduma baada ya kupokea tukio.

Unachopaswa kumwomba AI yako ya kujenga

Ongeza endpoint ya POST /webhooks/stripe kwenye seva. Hakiki sahihi ya Stripe kwa kutumia mwili ghafi wa ombi na siri STRIPE_WEBHOOK_SECRET. Kataa sahihi batili kwa 400. Hifadhi kila kitambulisho cha tukio na uruke matukio yaliyoshachakatwa. Jibu 200 haraka, kisha shughulikia checkout.session.completed kwa kuweka oda kuwa imelipwa na kutuma risiti. Rekodi aina ya tukio. Usitoe ufikiaji kutoka ukurasa wa mafanikio wa checkout.

Kisha jaribu: tuma tukio la majaribio kutoka dashibodi ya mtoa huduma, tuma tukio hilohilo tena, na tuma ombi lenye sahihi isiyo sahihi. Ni la kwanza tu linapaswa kubadilisha chochote.

Webhooks kwenye Mythex

Mythex haiendeshi huduma tofauti ya webhooks; unamwomba wakala aongeze endpoint ya webhook kwenye backend ya programu yako yenyewe, kisha umwelekeze mtoa huduma kwenye URL yako iliyochapishwa, kwa sababu webhooks zinahitaji anwani ya umma. Siri ya kusaini inaingia kwenye siri za mradi wako, na ukibadilisha kwenye programu hai, chapisha tena. Kichocheo cha nyaraka kuhusu kushughulikia webhooks kina kidokezo cha kuanzia, na violezo vya maduka ni mahali pazuri pa kuanzia kwa programu zinazokubali malipo.

Maswali