Ի՞նչ է webhook-ը։ Ինչպես են հավելվածները միմյանց տեղեկացնում

Webhook-ը ավտոմատ հաղորդագրություն է, որը մի ծառայություն ուղարկում է ձեր հավելվածին այն պահին, երբ ինչ-որ բան է տեղի ունենում։ Երբ հաճախորդի վճարումը հաջողվում է, Stripe-ը ձեր հավելվածի մի հասցեին webhook է ուղարկում, որում ասված է՝ «վճարումը հաջողվեց, ահա մանրամասները», և ձեր հավելվածը արձագանքում է՝ նշում է պատվերը որպես վճարված, ուղարկում է անդորրագիրը, ապակողպում է հաշիվը։ Կարճ ասած՝ API-ն ձեր հավելվածի հարցն է մեկ այլ ծառայությանը, իսկ webhook-ը՝ մյուս ծառայության կանչը ձեր հավելվածին՝ ինչ-որ բան ասելու համար։

Ինչու է այն կարևոր AI-ով կառուցելիս

Այն պահից, երբ ձեր հավելվածը ընդունում է վճարումներ, ստանում է ձևերի տվյալներ մեկ այլ գործիքից կամ միանում է այնպիսի ծառայությունների, ինչպիսիք են GitHub-ը, Shopify-ը կամ օրացույցը, դուք կհանդիպեք webhook-ների։ Դրանք սովորաբար ճիշտ ձևն են իմանալու, որ ինչ-որ բան տեղի է ունեցել, բայց նաև այն տեղն են, որտեղ AI-ով կառուցված հավելվածները հաճախ նրբորեն սխալ են լինում․

• Վերջնակետը (endpoint) ընդունում է ցանկացած հարցում, ուստի ցանկացած մեկը կարող է կեղծել «վճարումը հաջողվեց» իրադարձությունը։
• Հավելվածը հաշվառում է մուտքը վճարման վերահղման էջում՝ ոչ թե webhook-ում, այնպես որ այն մարդիկ, ովքեր շուտ են փակում էջը, երբեք չեն ստանում այն, ինչի համար վճարել են, իսկ ովքեր գտնում են հաջողության URL-ը՝ ստանում են անվճար։
• Նույն իրադարձությունը երկու անգամ է գալիս, և հաճախորդը ստանում է երկու պատվեր կամ երկու նամակ։

Պատկերացնելը, թե ինչպես են աշխատում webhook-ները, թույլ է տալիս ծրագրավորման ժամանակ պահանջել պաշտպանությունները։

Ամենօրյա անալոգիա՝ առաքման SMS

Կարող եք իմանալ, թե արդյոք ձեր փաթեթը հասել է, երկու եղանակով։ Կարող եք ամեն տասը րոպեն մեկ գնալ դռան մոտ և ստուգել (դա polling է՝ երբ ձեր հավելվածը մշտապես կանչում է API-ին՝ հարցնելու «նորություն կա՞»)։ Կամ կուրիերը կարող է SMS ուղարկել, երբ առաքում է (դա webhook-ն է)։

SMS-ը հստակ ավելի լավն է՝ եթե կարող եք դրան վստահել։ Եթե ցանկացած մեկը կարող էր ուղարկել ձեզ «փաթեթը առաքված է» հաղորդագրություն, կուզենայիք ինչ-որ միջոց իմանալու, որ այն իրոք կուրիերից է եկել։ Իսկ եթե հեռախոսը անջատված էր, երբ SMS-ը եկավ, կուզենայիք, որ կուրիերը ավելի ուշ նորից փորձեր։ Այդ երկու մտահոգությունները՝ ստուգումը և կրկնվող փորձերը, webhook-ները դժվար դարձնող հիմնական բաներն են։

Ինչպես է աշխատում webhook-ը, քայլ առ քայլ

1. Դուք ստեղծում եք վերջնակետ ձեր հավելվածի backend-ում՝ URL, օրինակ՝ https://yourapp.com/webhooks/stripe, որն ընդունում է POST հարցումներ։
2. Դուք գրանցում եք այդ URL-ը մատակարարի մոտ և ընտրում եք, թե որ իրադարձություններն եք ուզում (օրինակ՝ «checkout ավարտվեց» և «բաժանորդագրությունը չեղարկվեց»)։
3. Մատակարարը տալիս է ստորագրման գաղտնիք։ Դուք պահում եք այն որպես գաղտնիք ձեր սերվերում՝ տե՛ս միջավայրի փոփոխականներ և գաղտնիքներ։
4. Իրադարձություն է տեղի ունենում։ Մատակարարը HTTP հարցում է ուղարկում ձեր URL-ին՝ JSON մարմնով, որը նկարագրում է այն, և ստորագրության վերնագրով։
5. Ձեր հավելվածը ստուգում է ստորագրությունը, գրանցում իրադարձության ID-ն, արագ պատասխանում հաջողության կոդով (200) և ապա կատարում աշխատանքը։
6. Եթե ձեր հավելվածը հաջողության պատասխան չի տալիս, շատ մատակարարներ ավելի ուշ նորից են փորձում։

Ստորագրություններ

Ստորագրությունը ապացուցում է, որ հարցումը մատակարարից է եկել և չի փոխվել։ Օրինակ՝ Stripe-ը հաշվարկում է HMAC-ը (բանալիով պահպանված մատնահետք) SHA-256 ալգորիթմով՝ հարցման մարմնի և ժամանակի դրոշմի վրա՝ օգտագործելով ստորագրման գաղտնիքը, և այն ուղարկում է Stripe-Signature վերնագրում։ Ձեր հավելվածը նույն հաշվարկն է կատարում իր պատճենով․ եթե արդյունքները համընկնում են, հարցումը իսկական է։ Քանի որ ժամանակի դրոշմն էլ է ստորագրված, կարող եք մերժել հին հարցումները, որոնք որևէ մեկը գրանցել և հետո կրկնել է։ Stripe-ի գրադարանները լռելյայն ունեն հինգ րոպե հանդուրժողականություն՝ ըստ նրա փաստաթղթերի՝ սեպտեմբեր 2026-ի դրությամբ։

Պրակտիկ մանրամասն․ ստորագրությունը հաշվարկվում է հարցման չմշակված մարմնի վրա։ Եթե ձեր շրջանակը վերլուծում և վերաձևավորում է JSON-ը նախքան ստուգելը, ստուգումը ձախողվում է։ Սա շատ տարածված սխալ է։

Կրկնվող փորձեր, կրկնօրինակներ և հերթականություն

Մատակարարները տարբերվում են, ուստի ստուգեք յուրաքանչյուրի փաստաթղթերը։ Սեպտեմբեր 2026-ի դրությամբ՝

Stripe-ի փաստաթղթերը նաև ասում են, որ իրադարձությունները երաշխավորված չեն գալ այն հերթականությամբ, որով տեղի են ունեցել, և որ նույն իրադարձությունը երբեմն կարող է գալ մեկից ավելի անգամ, ուստի խորհուրդ է տալիս հետևել իրադարձությունների ID-ներին։

Ընդհանուր դասը գործում է ցանկացած մատակարարի համար․ իրադարձությունները կարող են գալ ուշացումով, մեկից ավելի անգամ և անկարգ հերթականությամբ։ Ձեր մշակիչը պետք է լինի իդեմպոտենտ՝ նույն իրադարձությունը երկու անգամ մշակելը ունենա նույն ազդեցությունը, ինչ մեկ անգամ մշակելը։

Աշխատած օրինակ՝ վճարված դասընթացի բացում

Դուք վաճառում եք առցանց դասընթաց։ Ուսանողը սեղմում է Գնել, վճարում է Stripe-ի հյուրընկալվող checkout էջում և վերադարձվում է ձեր կայք։

Փխրուն ձևը․ «Շնորհակալություն» էջը բացում է դասընթացը։ Եթե ուսանողը վերահղման ընթացքում փակում է դիտարկիչը, նա վճարել է, բայց մուտք չունի։ Եթե որևէ մեկը գուշակում է շնորհակալության URL-ը, նա մուտք է ստանում առանց վճարելու։

Webhook-ի ձևը․

1. Երբ Stripe-ը հաստատում է վճարումը, այն ուղարկում է checkout.session.completed իրադարձություն /webhooks/stripe-ին։
2. Ձեր backend-ը ստուգում է ստորագրությունը ստորագրման գաղտնիքով։ Եթե այն ձախողվում է, պատասխանում է 400 և ոչինչ չի անում։
3. Ստուգում է, արդյոք այդ իրադարձության ID-ն արդեն մշակվել է։ Եթե այո, պատասխանում է 200 և կանգ է առնում։
4. Պահում է իրադարձության ID-ն, պատասխանում է 200, ապա տրամադրում է ուսանողին մուտք և ուղարկում է բարի գալստյան նամակ։
5. Շնորհակալության էջը պարզապես ասում է «Վճարումը ստացվել է՝ ձեր դասընթացը շուտով կհայտնվի» և ստուգում է ուսանողի մուտքի կարգավիճակը։

Հետագայում, եթե բաժանորդագրությունը չեղարկվի կամ քարտը մերժվի, այլ webhook իրադարձություններ ասում են ձեր հավելվածին հեռացնել կամ դադարեցնել մուտքը։ Այսպես բաժանորդագրական արտադրանքները համաժամանակ են մնում հաշվարկման հետ՝ տե՛ս ինչ է SaaS-ը և ինչպես ավելացնել վճարումներ ձեր հավելվածին։

Հիմնական տերմիններ

• Endpoint (վերջնակետ)․ Ձեր հավելվածի URL, որը ընդունում է webhook-ները։
• Իրադարձություն / payload․ Ինչ է տեղի ունեցել և այն նկարագրող տվյալները (սովորաբար JSON)։
• Ստորագրման գաղտնիք (signing secret)․ Ընդհանուր գաղտնիքը, որով ստուգվում են ստորագրությունները։
• Իդեմպոտենտ (idempotent)․ Անվտանգ է նույն արդյունքով մեկից ավելի անգամ կատարել։
• Polling (հարցում)․ Կրկնվող հարցնել API-ին փոփոխությունների մասին՝ webhook-ի սպասելու փոխարեն։
• Tunnel (թունել)․ Գործիք, որը տեղական համակարգչին ժամանակավոր հրապարակային URL է տալիս, որպեսզի webhook-ները հասնեն դրան մշակման ժամանակ։

Սովորական սխալներ և թյուրըմբռնումներ

• Ստորագրությունները չստուգելը։ Վերջնակետի URL-ը գաղտնիք չէ։ Ստուգումն է, որ հարցումը վստահելի է դարձնում։
• Դանդաղ աշխատանք կատարելը պատասխանելուց առաջ։ Նամակների կամ PDF-ների ստեղծումը նախքան պատասխանելը կարող է առաջացնել ժամանակի սպառում, որն ակտիվացնում է կրկնվող փորձերը, որոնք առաջացնում են կրկնօրինակներ։
• Ենթադրել, որ ճիշտ մեկ անգամ, ճիշտ հերթականությամբ։ Գրանցեք իրադարձությունների ID-ները և մի ապավինեք ժամանման հերթականությանը։
• Նախադիտման URL օգտագործելը։ Webhook-ներին անհրաժեշտ է կայուն, հրապարակային հասցե։ Մասնավոր նախադիտումները և localhost-ը ինտերնետից անհասանելի են․ օգտագործեք ձեր հրապարակված URL-ը (կամ թունել՝ փորձարկելիս)։
• Թեստային և կենդանի գաղտնիքները խառնելը։ Մատակարարները հաճախ տարբեր ստորագրման գաղտնիքներ են տալիս թեստային և կենդանի ռեժիմների համար։ Պահեք երկուսն էլ և օգտագործեք ճիշտը։
• Բեռնվածքին կույր վստահելը կարևոր որոշումների համար։ Բարձր խաղադրույքով գործողությունների համար ողջամիտ է իրադարձությունը ստանալուց հետո մատակարարի API-ից վերցնել վերջին վիճակը։

Ինչ խնդրել ձեր AI builder-ից

Ավելացրու POST /webhooks/stripe վերջնակետ սերվերում։ Ստուգիր Stripe ստորագրությունը չմշակված հարցման մարմնով և STRIPE_WEBHOOK_SECRET գաղտնիքով։ Անվավեր ստորագրությունները մերժիր 400-ով։ Պահիր յուրաքանչյուր իրադարձության ID-ն և բաց թող արդեն մշակվածները։ Արագ պատասխանիր 200-ով, ապա մշակիր checkout.session.completed՝ նշելով պատվերը որպես վճարված և ուղարկելով անդորրագիրը։ Գրանցիր իրադարձության տեսակը։ Մի տրամադրիր մուտք checkout-ի հաջողության էջից։

Այնուհետև փորձարկեք այն․ մատակարարի վահանակից ուղարկեք թեստային իրադարձություն, նորից ուղարկեք նույնը և ուղարկեք սխալ ստորագրությամբ հարցում։ Միայն առաջինը պետք է ինչ-որ բան փոխի։

Webhook-ները Mythex-ում

Mythex-ն առանձին webhook ծառայություն չունի․ դուք խնդրում եք գործակալին ավելացնել webhook վերջնակետ ձեր հավելվածի սեփական backend-ում և մատակարարին ցույց տալ ձեր հրապարակված URL-ը, քանի որ webhook-ներին անհրաժեշտ է հրապարակային հասցե։ Ստորագրման գաղտնիքը գնում է ձեր նախագծի գաղտնիքների մեջ, և եթե այն փոխում եք կենդանի հավելվածում, նորից հրապարակում եք։ Փաստաթղթերի webhook-ների մշակման ռեցեպտը ունի մեկնարկային հրահանգ, իսկ խանութի ձևանմուշները լավ մեկնակետ են վճարումներ ընդունող հավելվածների համար։

Հարցեր