Kas yra webhook? Kaip programos praneša viena kitai

Webhook – tai automatinė žinutė, kurią viena paslauga siunčia jūsų programai tą akimirką, kai kas nors įvyksta. Kai klientas sėkmingai sumoka, Stripe siunčia webhook į jūsų programos adresą su žinute „mokėjimas sėkmingas, štai detalės“, o jūsų programa reaguoja – pažymi užsakymą apmokėtu, išsiunčia čekį, atrakina paskyrą. Trumpai: API – tai jūsų programa klausia kitos paslaugos; webhook – tai kita paslauga iškviečia jūsų programą ir praneša apie kažką.

Kodėl tai svarbu kuriant su DI

Kai tik jūsų programa priima mokėjimus, gauna formų pateikimus iš kito įrankio ar jungiasi prie tokių paslaugų kaip GitHub, Shopify ar kalendorius, susidursite su webhook. Dažniausiai jie yra teisingas būdas sužinoti, kad kas nors įvyko – bet būtent čia DI sukurtos programos dažniausiai yra subtiliai neteisingos:

• Galutinis taškas priima bet kokią užklausą, todėl bet kas gali suklastoti įvykį „mokėjimas sėkmingas“.
• Programa suteikia prieigą mokėjimo nukreipimo puslapyje, o ne webhook metu, todėl žmonės, kurie uždaro langą anksti, negauna to, ką apmokėjo, o tie, kurie suranda sėkmės URL, gauna nemokamai.
• Tas pats įvykis atkeliauja du kartus, ir klientas gauna du užsakymus ar du laiškus.

Žinodami, kaip veikia webhook, galite iš anksto paprašyti tų apsaugų.

Kasdienė analogija: pristatymo žinutė

Galite sužinoti, ar jūsų siuntinys atkeliavo, dviem būdais. Galite kas dešimt minučių eiti prie durų patikrinti (tai apklausa – jūsų programa nuolat kviečia API klausti „ar yra kas nors naujo?“). Arba kurjeris gali jums parašyti žinutę, kai pristato (tai webhook).

Žinutė akivaizdžiai geresnė – jei galite jai pasitikėti. Jei bet kas galėtų jums siųsti žinutę „siuntinys pristatytas“, norėtumėte būdo įsitikinti, kad ją tikrai atsiuntė kurjeris. O jei telefonas buvo išjungtas, kai žinutė atėjo, norėtumėte, kad kurjeris bandytų vėliau. Šios dvi problemos – patikrinimas ir pakartojimai – yra didžioji dalis to, kas webhook daro sudėtingais.

Kaip veikia webhook, žingsnis po žingsnio

1. Sukuriate galutinį tašką jūsų programos serveryje: URL, pavyzdžiui https://yourapp.com/webhooks/stripe, kuris priima POST užklausas.
2. Šį URL užregistruojate teikėjui ir pasirenkate, kokių įvykių norite (pavyzdžiui, „checkout completed“ ir „subscription cancelled“).
3. Teikėjas jums suteikia pasirašymo paslaptį. Ją išsaugote kaip paslaptį savo serveryje – žr. aplinkos kintamuosius ir paslaptis.
4. Įvyksta įvykis. Teikėjas siunčia HTTP užklausą į jūsų URL su JSON turiniu, aprašančiu įvykį, ir parašo antraštę.
5. Jūsų programa patikrina parašą, įrašo įvykio ID, greitai atsako sėkmės kodu (200) ir tik tada atlieka darbą.
6. Jei jūsų programa neatsako sėkme, daugelis teikėjų bando vėliau dar kartą.

Parašai

Parašas įrodo, kad užklausą atsiuntė teikėjas ir kad ji nebuvo pakeista. Stripe, pavyzdžiui, apskaičiuoja HMAC (tam tikrą raktu paremtą kontrolinę sumą) su SHA-256 per užklausos turinį ir laiko žymę, naudodamas pasirašymo paslaptį, ir siunčia ją Stripe-Signature antraštėje. Jūsų programa atlieka tą patį skaičiavimą su savo paslapties kopija; jei rezultatai sutampa, užklausa tikra. Kadangi laiko žymė taip pat pasirašyta, galite atmesti senas užklausas, kurias kas nors įrašė ir vėliau pakartojo – Stripe bibliotekos pagal numatytuosius nustatymus leidžia penkių minučių nuokrypį, pagal jų dokumentaciją 2026 m. rugsėjo mėn.

Praktinis niuansas: parašas skaičiuojamas nuo neapdoroto užklausos turinio. Jei jūsų sistema prieš tikrinant išanalizuoja ir performatuoja JSON, patikrinimas nepavyksta. Tai labai dažna klaida.

Pakartojimai, dublikatai ir tvarka

Teikėjai skiriasi, todėl patikrinkite kiekvieno dokumentaciją. Nuo 2026 m. rugsėjo:

Stripe dokumentacijoje taip pat sakoma, kad įvykiai negarantuotai atkeliauja tokia tvarka, kokia įvyko, ir kad tas pats įvykis retkarčiais gali atkeliauti daugiau nei vieną kartą, todėl rekomenduoja sekti įvykių ID.

Bendra pamoka galioja bet kuriam teikėjui: įvykiai gali atkeliauti pavėluotai, daugiau nei vieną kartą ir netinkama tvarka. Jūsų apdorojimas turi būti idempotentiškas – tas pats įvykis, apdorotas du kartus, turi tokį patį poveikį kaip apdorotas vieną kartą.

Pavyzdys: apmokėto kurso atrakinimas

Parduodate internetinį kursą. Studentas spaudžia Pirkti, moka Stripe talpinamame apmokėjimo puslapyje ir grąžinamas į jūsų svetainę.

Trapus būdas: „ačiū“ puslapis atrakina kursą. Jei studentas uždaro naršyklę nukreipimo metu, jis sumokėjo, bet prieigos neturi. Jei kas nors atspėja „ačiū“ URL, jis gauna prieigą nemokamai.

Webhook būdas:

1. Kai Stripe patvirtina mokėjimą, jis siunčia įvykį checkout.session.completed į /webhooks/stripe.
2. Jūsų serveris patikrina parašą su pasirašymo paslaptimi. Jei jis neatitinka, atsako 400 ir nieko nedaro.
3. Tikrinama, ar šis įvykio ID jau apdorotas. Jei taip, atsakoma 200 ir sustojama.
4. Įvykio ID išsaugomas, atsakoma 200, tada studentui suteikiama prieiga ir išsiunčiamas sveikinimo laiškas.
5. „Ačiū“ puslapis tiesiog sako „Mokėjimas gautas – kursas pasirodys po akimirkos“ ir tikrina studento prieigos būseną.

Vėliau, jei prenumerata atšaukiama arba kortelė atmetama, kiti webhook įvykiai nurodo jūsų programai pašalinti ar sustabdyti prieigą. Taip prenumeratos produktai išlieka sinchronizuoti su atsiskaitymu – žr. kas yra SaaS ir kaip pridėti mokėjimus į savo programą.

Pagrindiniai terminai

• Galutinis taškas (endpoint): jūsų programos URL, kuris priima webhook.
• Įvykis / turinys (event / payload): kas įvyko ir duomenys, jį aprašantys (paprastai JSON).
• Pasirašymo paslaptis (signing secret): bendra paslaptis parašams tikrinti.
• Idempotentiškas: saugu paleisti kelis kartus su tuo pačiu rezultatu.
• Apklausa (polling): nuolat klausti API apie pakeitimus, užuot laukus webhook.
• Tunelis (tunnel): įrankis, suteikiantis nešiojamajam kompiuteriui laikiną viešą URL, kad webhook pasiektų jį kūrimo metu.

Dažnos klaidos ir mitai

• Parašų netikrinimas. Galutinio taško URL nėra paslaptis. Tikrinimas ir daro užklausą patikimą.
• Lėto darbo atlikimas prieš atsakant. El. laiškų siuntimas ar PDF generavimas prieš atsakymą gali sukelti laiko viršijimą, o tai sukelia pakartojimus, o pakartojimai – dublikatus.
• Prielaida, kad įvykis atkeliauja tik vieną kartą ir tvarkingai. Įrašykite įvykių ID ir nesiremkite atvykimo tvarka.
• Peržiūros URL naudojimas. Webhook reikia stabilaus, viešo adreso. Privačios peržiūros ir localhost nepasiekiami iš interneto; naudokite savo paskelbtą URL (arba tunelį testavimo metu).
• Testinių ir tiesioginių paslapčių maišymas. Teikėjai dažnai išduoda skirtingas pasirašymo paslaptis testiniam ir tiesioginiam režimams. Saugokite abi ir naudokite tinkamą.
• Duomenų aklas pasitikėjimas svarbiems sprendimams. Didelės rizikos veiksmams pagrįsta gauti naujausią būseną iš teikėjo API, gavus įvykį.

Ką paprašyti DI kūrėjo

Pridėk POST /webhooks/stripe galutinį tašką serveryje. Patikrink Stripe parašą naudodamas neapdorotą užklausos turinį ir paslaptį STRIPE_WEBHOOK_SECRET. Atmesk neteisingus parašus su 400. Įrašyk kiekvieną įvykio ID ir praleisk jau apdorotus įvykius. Greitai atsakyk 200, tada apdorok checkout.session.completed: pažymėk užsakymą apmokėtu ir išsiųsk kvitą. Įrašyk įvykio tipą į žurnalą. Neatrakink prieigos sėkmės puslapyje.

Tada patikrinkite: iš teikėjo panelės išsiųskite testinį įvykį, tą patį siųskite dar kartą ir siųskite užklausą su neteisingu parašu. Pakeitimą turėtų padaryti tik pirmasis.

Webhook Mythex platformoje

Mythex neturi atskiros webhook paslaugos; jūs paprašote agento pridėti webhook galutinį tašką į savo programos backend ir nukreipti teikėją į savo paskelbtą URL, nes webhook reikia viešo adreso. Pasirašymo paslaptis įdedama į projekto paslaptis, o jei ją pakeičiate veikiančioje programoje, paskelbiate iš naujo. Dokumentacijos receptas webhook tvarkymas turi pradinę užklausą, o parduotuvių šablonai yra geras pradžios taškas programoms, priimančioms mokėjimus.

Klausimai