Çfarë është një webhook? Si aplikacionet njoftojnë njëri-tjetrin

Një webhook është një mesazh automatik që një shërbim ia dërgon aplikacionit tënd në çastin kur ndodh diçka. Kur pagesa e një klienti kalon me sukses, Stripe dërgon një webhook te një adresë në aplikacionin tënd që thotë “pagesa u krye, ja detajet”, dhe aplikacioni reagon — e shënon porosinë si të paguar, dërgon faturën, zhbllokon llogarinë. Shkurtimisht: një API është aplikacioni yt që i bën një pyetje një shërbimi tjetër; një webhook është shërbimi tjetër që thërret aplikacionin tënd për t’i thënë diçka.

Pse ka rëndësi kur ndërton me AI

Sapo aplikacioni yt pranon pagesa, merr dorëzime formularësh nga një mjet tjetër, ose lidhet me shërbime si GitHub, Shopify ose një kalendar, do të takosh webhook-et. Zakonisht janë mënyra e saktë për të ditur që diçka ndodhi — por janë edhe vendi ku aplikacionet e ndërtuara me AI gabojnë më shpesh, në mënyra të fshehta:

• Endpoint-i pranon çdo kërkesë, kështu që kushdo mund të falsifikojë një ngjarje “pagesa u krye”.
• Aplikacioni jep qasje te faqja e ridrejtimit të pagesës në vend të webhook-ut, kështu që njerëzit që mbyllin skedën herët nuk marrin atë për të cilën paguan, ndërsa ata që gjejnë URL-në e suksesit e marrin falas.
• E njëjta ngjarje arrin dy herë dhe klienti merr dy porosi ose dy email.

Njohja e funksionimit të webhook-eve të lejon të kërkosh mbrojtjet që në fillim.

Një analogji e përditshme: një SMS për dërgesën

Mund ta dish nëse pakoja jote ka mbërritur në dy mënyra. Mund të ecësh te dera e përparme çdo dhjetë minuta për ta kontrolluar (kjo quhet polling — aplikacioni yt thërret vazhdimisht një API për të pyetur “a ka gjë të re?”). Ose kurieri mund të të dërgojë një SMS kur të dorëzohet (ky është një webhook).

SMS-i është qartësisht më i mirë — me kusht që t’i besosh. Nëse kushdo mund të të dërgonte një mesazh “pakoja u dorëzua”, do të donit një mënyrë për të ditur që vjen vërtet nga kurieri. Dhe nëse telefoni yt ishte i fikur kur erdhi SMS-i, do të donit që kurieri ta provonte përsëri më vonë. Këto dy shqetësime — verifikimi dhe rifillimet — janë shumica e asaj që i bën webhook-et të vështira.

Si funksionon një webhook, hap pas hapi

1. Krijon një endpoint në backend-in e aplikacionit tënd: një URL si https://yourapp.com/webhooks/stripe që pranon kërkesa POST.
2. Regjistron atë URL te ofruesi dhe zgjedh cilat ngjarje të duhen (për shembull, “checkout u përfundua” dhe “abonimi u anulua”).
3. Ofruesi të jep një sekret nënshkrimi. E ruan si sekret në serverin tënd — shih variablat e mjedisit dhe sekretet.
4. Ndodh një ngjarje. Ofruesi dërgon një kërkesë HTTP te URL-ja jote me një body JSON që e përshkruan, plus një header nënshkrimi.
5. Aplikacioni yt verifikon nënshkrimin, regjistron ID-në e ngjarjes, kthen shpejt një kod suksesi (200), dhe pastaj kryen punën.
6. Nëse aplikacioni yt nuk kthen sukses, shumë ofrues provojnë përsëri më vonë.

Nënshkrimet

Një nënshkrim vërteton që kërkesa erdhi nga ofruesi dhe nuk u ndryshua. Stripe, për shembull, llogarit një HMAC (një lloj gjurmëve me çelës) me SHA-256 mbi body-n e kërkesës dhe një timestamp, duke përdorur sekretin e nënshkrimit, dhe e dërgon në header-in Stripe-Signature. Aplikacioni yt bën të njëjtin llogaritje me kopjen e vet të sekretit; nëse rezultatet përputhen, kërkesa është e vërtetë. Meqenëse timestamp-i nënshkruhet gjithashtu, mund të refuzosh kërkesa të vjetra që dikush i ka regjistruar dhe i ripërsërit më vonë — bibliotekat e Stripe përdorin si parazgjedhje një tolerancë pesë minutash, sipas dokumentacionit të tij që nga shtatori 2026.

Një detaj praktik: nënshkrimi llogaritet mbi body-n të papërpunuar të kërkesës. Nëse framework-u yt e analizon dhe ripaketon JSON-in përpara verifikimit, kontrolli dështon. Ky është një gabim shumë i zakonshëm.

Rifillimet, dublikatat dhe rendi

Ofruesit ndryshojnë, kontrollo dokumentacionin e secilit. Që nga shtatori 2026:

Dokumentacioni i Stripe thotë gjithashtu se ngjarjet nuk garantohen të arrijnë në të njëjtin rend me ndodhjen e tyre, dhe e njëjta ngjarje mund të arrijë herë të shumta; prandaj rekomandon ndjekjen e ID-ve të ngjarjeve.

Mësimi i përgjithshëm vlen për çdo ofrues: ngjarjet mund të arrijnë vonë, më shumë se një herë dhe jashtë rendit. Trajtuesi yt duhet të jetë idempotent — përpunimi i së njëjtës ngjarje dy herë ka të njëjtin efekt si përpunimi një herë.

Një shembull i punuar: zhbllokimi i një kursi të paguar

Shet një kurs online. Një student klikon Blej, paguan në faqen e checkout-it të hostuar nga Stripe, dhe kthehet në sajtin tënd.

Mënyra e brishtë: faqja “faleminderit” zhbllokon kursin. Nëse studenti mbyll shfletuesin gjatë ridrejtimit, ka paguar por nuk ka qasje. Nëse dikush hamendëson URL-në e faqes “faleminderit”, merr qasje pa paguar.

Mënyra me webhook:

1. Kur Stripe konfirmon pagesën, dërgon një ngjarje checkout.session.completed te /webhooks/stripe.
2. Backend-i yt verifikon nënshkrimin me sekretin e nënshkrimit. Nëse dështon, kthen 400 dhe nuk bën asgjë.
3. Kontrollon nëse ai ID ngjarjeje është përpunuar tashmë. Nëse po, kthen 200 dhe ndalon.
4. Ruan ID-në e ngjarjes, kthen 200, dhe pastaj i jep studentit qasje dhe dërgon një email mirëseardhjeje.
5. Faqja “faleminderit” thjesht thotë “Pagesa u mor — kursi yt do të shfaqet pas pak” dhe kontrollon statusin e qasjes së studentit.

Më vonë, nëse një abonim anulohet ose një kartë refuzohet, ngjarje të tjera webhook i thonë aplikacionit tënd të heqë ose pezullojë qasjen. Kështu produktet me abonim mbeten të sinkronizuara me faturimin — shih çfarë është SaaS dhe si të shtosh pagesa në aplikacionin tënd.

Termat kryesorë

• Endpoint: URL-ja në aplikacionin tënd që pranon webhook-et.
• Ngjarje / payload: çfarë ndodhi, dhe të dhënat që e përshkruajnë (zakonisht JSON).
• Sekret nënshkrimi: sekreti i ndarë që përdoret për verifikimin e nënshkrimeve.
• Idempotent: i sigurt për t’u ekzekutuar më shumë se një herë me të njëjtin rezultat.
• Polling: pyetja e përsëritur e një API për ndryshime, në vend që të presësh një webhook.
• Tunel: një mjet që i jep laptopit një URL publike të përkohshme, që webhook-et të arrijnë te ai gjatë zhvillimit.

Gabime dhe keqkuptime të zakonshme

• Mos verifikimi i nënshkrimeve. URL-ja e endpoint-it nuk është sekret. Verifikimi është ajo që e bën kërkesën të besueshme.
• Punë e ngadaltë para përgjigjes. Dërgimi i email-eve ose gjenerimi i PDF-ve para se të përgjigjesh mund të shkaktojë timeout, që shkakton rifillime, që shkaktojnë dublikata.
• Supozimi i saktësisht një herë, me rend. Regjistro ID-të e ngjarjeve dhe mos u mbështet në rendin e arritjes.
• Përdorimi i një URL preview. Webhook-et kanë nevojë për një adresë publike e qëndrueshme. Preview-të private dhe localhost nuk arrihen nga interneti; përdor URL-në e publikuar (ose një tunel gjatë testimit).
• Përzierja e sekreteve test dhe live. Ofruesit shpesh japin sekrete nënshkrimi të ndryshme për modalitetet test dhe live. Ruaji të dyja dhe përdor atë të duhurin.
• Besimi i verbër në payload për vendime të rëndësishme. Për veprime me rrezik të lartë, është e arsyeshme të marrësh gjendjen më të fundit nga API-ja e ofruesit pasi të marrësh ngjarjen.

Çfarë t’i kërkosh AI-së tënde ndërtuese

Shto një endpoint POST /webhooks/stripe në server. Verifiko nënshkrimin e Stripe duke përdorur body-n e papërpunuar të kërkesës dhe sekretin STRIPE_WEBHOOK_SECRET. Refuzo nënshkrimet e pavlefshme me 400. Ruaj çdo ID ngjarjeje dhe kapërce ngjarjet që janë përpunuar tashmë. Kthe 200 shpejt, pastaj trajto checkout.session.completed duke e shënuar porosinë si të paguar dhe duke dërguar faturën. Regjistro llojin e ngjarjes. Mos jep qasje nga faqja e suksesit të checkout-it.

Pastaj testoje: dërgo një ngjarje testuese nga paneli i ofruesit, dërgo të njëjtën përsëri, dhe dërgo një kërkesë me nënshkrim të gabuar. Vetëm e para duhet të ndryshojë diçka.

Webhook-et në Mythex

Mythex nuk ka një shërbim të veçantë për webhook-et; i kërkon agjentit të shtojë një endpoint webhook në backend-in e vetë aplikacionit, dhe e drejton ofruesin drejt URL-së tënde të publikuar, pasi webhook-et kanë nevojë për adresë publike. Sekreti i nënshkrimit shkon te sekretet e projektit, dhe nëse e ndryshon në një aplikacion live, publiko përsëri. Receta e dokumentacionit për trajtimin e webhook-eve ka një prompt fillestar, dhe shabllonet e dyqaneve janë një pikënisje e mirë për aplikacione që pranojnë pagesa.

Pyetje