Ano ang Webhook? Paano Nagpapaalam ang mga App sa Isa't Isa

Ang webhook ay awtomatikong mensaheng ipinapadala ng isang serbisyo sa app mo sa sandaling may mangyari. Kapag matagumpay ang bayad ng customer, magpapadala ang Stripe ng webhook sa address sa app mo na nagsasabing “naging matagumpay ang bayad, narito ang mga detalye”, at tutugon ang app mo — mamarkahan ang order bilang bayad, magpapadala ng resibo, bubuksan ang account. Sa madaling sabi: ang API ay ang app mo na nagtatanong sa ibang serbisyo; ang webhook ay ang ibang serbisyo na tumatawag sa app mo para magsabi ng isang bagay.

Bakit mahalaga ito kapag gumagawa ka gamit ang AI

Sa sandaling tumanggap ng bayad ang app mo, tumanggap ng form submission mula sa ibang tool, o kumonekta sa mga serbisyo gaya ng GitHub, Shopify o calendar, makakaharap mo ang webhook. Kadalasan ito ang tamang paraan para malaman na may nangyari — pero dito rin kadalasang mali nang palihim ang mga app na gawa sa AI:

• Tumatanggap ang endpoint ng anumang request, kaya sinuman ay makapagpapanggap na may “matagumpay na bayad”.
• Nagbibigay ang app ng access sa checkout redirect page sa halip na sa webhook, kaya ang mga nagsara ng tab nang maaga ay hindi nakukuha ang nabayaran nila, at ang mga nakahanap ng success URL ay nakakukuha ng libre.
• Dumarating nang dalawang beses ang parehong event at nakakatanggap ang customer ng dalawang order o dalawang email.

Kapag alam mo kung paano gumagana ang webhook, maaari mong hilingin ang mga proteksyon mula sa simula.

Isang pang-araw-araw na halimbawa: text ng delivery

May dalawang paraan para malaman kung dumating na ang parsela mo. Puwede kang lumabas sa pinto tuwing sampung minuto para tingnan (iyon ang polling — paulit-ulit na tumatawag ang app mo sa API para magtanong ng “may bago ba?”). O puwedeng mag-text ang courier kapag naihatid na (iyon ang webhook).

Mas mabuti ang text — basta mapagkakatiwalaan mo ito. Kung kahit sino ay makapagpapadala ng mensaheng “naihatid na ang parsela”, kailangan mo ng paraan para malamang galing talaga ito sa courier. At kung naka-off ang telepono mo nang dumating ang text, gusto mong sumubok ulit ang courier sa ibang pagkakataon. Ang dalawang alalahaning ito — verification at retries — ang halos bumubuo sa hirap ng webhook.

Paano gumagana ang webhook, hakbang-hakbang

1. Gumawa ka ng endpoint sa backend ng app mo: isang URL gaya ng https://yourapp.com/webhooks/stripe na tumatanggap ng POST request.
2. Irehistro mo ang URL na iyon sa provider at piliin kung aling mga event ang gusto mo (halimbawa, “checkout completed” at “subscription cancelled”).
3. Magbibigay ang provider ng signing secret. Itatago mo ito bilang secret sa server mo — tingnan ang environment variables at secrets.
4. May mangyaring event. Magpapadala ang provider ng HTTP request sa URL mo na may JSON body na naglalarawan dito, kasama ang signature header.
5. Ve-verify ng app mo ang signature, itatala ang event ID, mabilis na sasagot ng success code (200), at saka gagawin ang trabaho.
6. Kung hindi sasagot ang app mo ng success, maraming provider ang susubok ulit mamaya.

Mga signature

Pinatutunayan ng signature na galing sa provider ang request at hindi ito binago. Halimbawa, kinukuwenta ng Stripe ang HMAC (isang uri ng keyed fingerprint) gamit ang SHA-256 sa request body at timestamp, gamit ang signing secret, at ipinapadala ito sa Stripe-Signature header. Ginagawa rin ng app mo ang parehong kuwenta gamit ang sarili nitong kopya ng secret; kapag nagtugma ang resulta, totoo ang request. Dahil napipirmahan din ang timestamp, maaari mong tanggihan ang mga lumang request na naitala ng iba at ni-replay sa ibang panahon — ayon sa dokumentasyon ng Stripe noong Setyembre 2026, limang minutong tolerance ang default ng kanilang mga library.

Isang praktikal na detalye: ang signature ay kinukuwenta sa raw request body. Kapag ini-parse at inayos muna ng framework mo ang JSON bago mo i-verify, papalya ang check. Napakakaraniwang bug ito.

Mga retry, duplicate at pagkakasunod

Magkakaiba ang mga provider, kaya tingnan ang dokumentasyon ng bawat isa. Noong Setyembre 2026:

Sinasabi rin ng dokumentasyon ng Stripe na hindi garantisadong dadating ang mga event ayon sa pagkakasunod ng pangyayari, at maaaring dumating nang higit sa isang beses ang parehong event paminsan-minsan, kaya inirerekomenda nilang subaybayan ang mga event ID.

Totoo ang pangkalahatang aral para sa anumang provider: maaaring dumating nang huli, higit sa isang beses at wala sa tamang pagkakasunod ang mga event. Dapat idempotent ang handler mo — ang pagproseso ng parehong event nang dalawang beses ay may parehong epekto ng isang beses lang.

Isang halimbawang gawa: pag-unlock ng bayad na kurso

Nagbebenta ka ng online course. Ki-click ng estudyante ang Buy, magbabayad sa hosted checkout page ng Stripe, at ibabalik sa site mo.

Ang marupok na paraan: ina-unlock ng “salamat” na pahina ang kurso. Kung isasara ng estudyante ang browser habang nagre-redirect, nakabayad siya pero walang access. Kung mahulaan ng isang tao ang thank-you URL, makakakuha siya ng access nang hindi nagbabayad.

Ang paraan ng webhook:

1. Kapag kinumpirma ng Stripe ang bayad, magpapadala ito ng event na checkout.session.completed sa /webhooks/stripe.
2. Ive-verify ng backend mo ang signature gamit ang signing secret. Kapag pumalya, sasagot ito ng 400 at hindi gagawa ng anuman.
3. Titingnan nito kung naproseso na ang event ID na iyon. Kung oo, sasagot ng 200 at hihinto.
4. Ise-save nito ang event ID, sasagot ng 200, at saka ibibigay sa estudyante ang access at magpapadala ng welcome email.
5. Ang thank-you page ay magsasabing “Natanggap ang bayad — lilitaw sa sandali ang kurso mo” at titingnan ang status ng access ng estudyante.

Mamaya, kapag kinansela ang subscription o pumalya ang card, sasabihan ng ibang webhook event ang app mo na tanggalin o i-pause ang access. Ganito nananatiling magkasabay ang subscription product at billing — tingnan ang ano ang SaaS at paano magdagdag ng bayad sa app mo.

Mahahalagang termino

• Endpoint: ang URL sa app mo na tumatanggap ng webhook.
• Event / payload: kung ano ang nangyari, at ang datos na naglalarawan dito (karaniwang JSON).
• Signing secret: ang shared secret na ginagamit para i-verify ang signature.
• Idempotent: ligtas patakbuhin nang higit sa isang beses na may parehong resulta.
• Polling: paulit-ulit na pagtatanong sa isang API ng mga pagbabago sa halip na maghintay ng webhook.
• Tunnel: tool na nagbibigay ng pansamantalang pampublikong URL sa laptop para maabot ng webhook habang nagde-develop.

Karaniwang pagkakamali at maling akala

• Hindi pag-verify ng signature. Hindi lihim ang endpoint URL. Ang verification ang nagpapagkatiwalaan sa request.
• Mabagal na gawain bago sumagot. Ang pagpapadala ng email o paggawa ng PDF bago tumugon ay maaaring magdulot ng timeout, na mag-uudyok ng retry, na magdudulot ng duplicate.
• Pag-aakalang eksaktong isang beses at may tamang pagkakasunod. Itala ang event ID at huwag umasa sa pagkakasunod ng pagdating.
• Paggamit ng preview URL. Kailangan ng webhook ng matatag at pampublikong address. Hindi maaabot mula sa internet ang pribadong preview at localhost; gamitin ang published URL mo (o tunnel habang sumusubok).
• Paghahalo ng test at live na secret. Kadalasang nagbibigay ang mga provider ng magkaibang signing secret para sa test at live mode. Itago ang pareho at gamitin ang tama.
• Pagtitiwala nang bulag sa payload para sa mahahalagang desisyon. Para sa mga aksyong may malaking taya, makatuwirang kunin ang pinakabagong estado mula sa API ng provider matapos matanggap ang event.

Ano ang hihilingin sa AI builder mo

Magdagdag ng POST /webhooks/stripe na endpoint sa server. I-verify ang Stripe signature gamit ang raw request body at ang secret na STRIPE_WEBHOOK_SECRET. Tanggihan ang hindi tamang signature gamit ang 400. I-store ang bawat event ID at laktawan ang mga event na naproseso na. Sumagot agad ng 200, saka hawakan ang checkout.session.completed sa pamamagitan ng pagmamarka ng order bilang bayad at pagpapadala ng resibo. I-log ang uri ng event. Huwag magbigay ng access mula sa checkout success page.

Pagkatapos, subukan: magpadala ng test event mula sa dashboard ng provider, ipadala ulit ang parehong isa, at magpadala ng request na may maling signature. Ang una lang ang dapat magpabago ng kahit ano.

Mga webhook sa Mythex

Wala sa Mythex ang hiwalay na serbisyo ng webhook; hihilingin mo sa agent na magdagdag ng webhook endpoint sa sarili mong backend ng app, at ituturo mo ang provider sa published mong URL, dahil kailangan ng webhook ng pampublikong address. Ilalagay ang signing secret sa project secrets mo, at kapag binago mo ito sa live na app, mag-publish ulit. May starter prompt ang docs recipe tungkol sa paghawak ng webhooks, at magandang panimula para sa mga app na tumatanggap ng bayad ang store templates.

Mga tanong