Webhook дегеніміз не? Қолданбалар бір-бірін қалай хабарлайды

Webhook — бірдеңе болған сәтте бір қызметтің қолданбаңызға жіберетін автоматты хабары. Клиенттің төлемі сәтті өткенде Stripe қолданбаңыздағы мекенжайға webhook жібереді: «төлем сәтті өтті, мәліметтері мынау», ал қолданбаңыз соған әрекет етеді — тапсырысты төленді деп белгілейді, түбіртек жібереді, аккаунтты ашады. Қысқаша: API — қолданбаңыздың басқа қызметтен сұрақ қоюы; webhook — басқа қызметтің сізге бірдеңе айту үшін қолданбаңызға қоңырау шалуы.

Неге ол AI-мен құрастырған кезде маңызды

Қолданбаңыз төлем қабылдаған, басқа құралдан форма жіберілгенін алған немесе GitHub, Shopify немесе күнтізбе сияқты қызметтерге қосылған сәтте webhook-пен кездесесіз. Көбіне олар бірдеңенің болғанын білудің дұрыс тәсілі — бірақ дәл осы жерде AI-мен құрастырылған қолданбалар жиі нәзік қателеседі:

• Соңғы нүкте кез келген сұранысты қабылдайды, сондықтан кез келген адам жалған «төлем сәтті өтті» оқиғасын жібере алады.
• Қолданба қолжетімділікті webhook-тың орнына төлем рәсімінен кейінгі бетте береді, сондықтан беттен ерте шыққан адамдар төлеген нәрсесін ала алмайды, ал сәттілік URL-ын тапқан адамдар оны тегін алады.
• Бір оқиға екі рет келеді де, клиент екі тапсырыс немесе екі хат алады.

Webhook қалай жұмыс істейтінін білу, қорғаныстарды алдын ала сұрауға көмектеседі.

Күнделікті салыстыру: курьер хабарламасы

Посылкаңыз келгенін екі жолмен біле аласыз. Оны біліп алу үшін ар жиырма минут сайын үйдің есігіне барып тексеруге болады (бұл polling — қолданбаңыз API-ға қайта-қайта «жаңа бірдеңе бар ма?» деп сұрайды). Немесе курьер жеткізілгенде хабарлама жіберуі мүмкін (бұл webhook).

Хабарлама анық жақсырақ — егер оған сене алсаңыз. Егер кез келген адам сізге «посылка жеткізілді» хабарын жібере алса, ол курьерден келгенін тексеруге мүмкіндік қажет. Ал хабарлама келгенде телефоныңыз өшірулі болса, курьердің кейінірек қайта әрекет етуін қалар едіңіз. Осы екі мәселе — растау және қайталаулар — webhook-ты қиындататынның көбі.

Webhook қадам-қадам қалай жұмыс істейді

1. Соңғы нүкте жасайсыз. Қолданбаңыздың backend-інде POST сұрауларын қабылдайтын мекенжай жасайсыз, мысалы https://yourapp.com/webhooks/stripe.
2. Мекенжайды провайдерде тіркейсіз және қандай оқиғаларды алғыңыз келетінін таңдайсыз (мысалы, «checkout аяқталды» және «жазылым тоқтатылды»).
3. Провайдер қолтаңба құпия кілтін береді. Оны серверде құпия ретінде сақтайсыз — қараңыз: орта айнымалылары мен құпиялар.
4. Оқиға болады. Провайдер сіздің URL-ға оны сипаттайтын JSON денесі және қолтаңба тақырыбы бар HTTP сұрауын жібереді.
5. Қолданбаңыз қолтаңбаны тексереді, оқиға ID-ін жазып алады, жылдам жауап кодын (200) қайтарады, содан кейін жұмысын жасайды.
6. Қолданбаңыз сәтті жауап бермесе, көптеген провайдерлер кейінірек қайта әрекет етеді.

Қолтаңбалар

Қолтаңба сұраныстың провайдерден келгенін және өзгертілмегенін дәлелдейді. Мысалы, Stripe сұраныс денесі мен уақыт белгісі бойынша SHA-256 HMAC (кілтпен жасалған саусақ ізі) есептейді, оны құпия кілтпен жасайды және Stripe-Signature тақырыбында жібереді. Қолданбаңыз өз құпия көшірмесімен дәл осы есептеуді жасайды; нәтижелер сәйкес келсе, сұраныс нақты. Уақыт белгісі де қолтаңбаланғандықтан, біреу жазып алып, кейін қайта ойнатқан ескі сұраныстарды қабылдамауға болады — Stripe кітапханалары құжаттамасына сәйкес, қыркүйек 2026 жылғы жағдай бойынша, әдепкі бойынша бес минуттық рұқсат береді.

Бір практикалық детализация: қолтаңба шикі сұраныс денесінде есептеледі. Егер фреймворкіңіз тексермес бұрын JSON-ды талдап, қайта форматтаса, тексеру сәтсіз болады. Бұл өте жиі кездесетін қате.

Қайталаулар, дубликаттар және реті

Провайдерлер әр түрлі, сондықтан әр құжаттаманы тексеріңіз. 2026 жылдың қыркүйегі жағдайы бойынша:

Stripe құжаттамасы оқиғалардың болған ретімен келуіне кепілдік жоқ екенін және бір оқиға кейде бірнеше рет келуі мүмкін екенін айтады, сондықтан оқиға ID-лерін бақылауды ұсынады.

Жалпы сабақ кез келген провайдерге қатысты: оқиғалар кешігіп, бірнеше рет және ретсіз келуі мүмкін. Өңдеушіңіз идемпотентті болуы керек — бір оқиғаны екі рет өңдеу, оны бір рет өңдеумен бірдей әсер беруі керек.

Жұмыс мысалы: ақылы курсты ашу

Сізде онлайн курс бар. Оқушы Сатып алу түймесін басып, Stripe-тың хостингтегі төлем бетінде төлейді де, сайтыңызға қайтарылады.

Осалдау жол: «рахмет» беті курсты ашады. Егер оқушы қайта бағыттау кезінде браузерді жапса, ол төлеген, бірақ қолжетімділігі жоқ. Егер біреу рахмет беті URL-ын болжаса, ол төлемей-ақ қолжетімділік алады.

Webhook жолы:

1. Stripe төлемді растағанда, /webhooks/stripe мекенжайына checkout.session.completed оқиғасын жібереді.
2. Backend қолтаңбаны құпия кілтпен тексереді. Сәтсіз болса, 400 қайтарады және ештеңе жасамайды.
3. Бұл оқиға ID-і бұрын өңделгенін тексереді. Иә болса, 200 қайтарып, тоқтайды.
4. Оқиға ID-ін сақтайды, 200 қайтарады, содан кейін оқушыға қолжетімділік береді және қош келдіңіз хатын жібереді.
5. Рахмет беті жай ғана «Төлем қабылданды — курсыңыз бір сәттен кейін пайда болады» деп айтады және оқушының қолжетімділік күйін тексереді.

Кейінірек жазылым тоқтатылса немесе карта қабылданбаса, басқа webhook оқиғалары қолданбаңызға қолжетімділікті алып тастауды немесе кідіртуді айтады. Жазылым өнімдері осылай төлем жүйесімен үйлесімді күйде қалады — қараңыз: SaaS дегеніміз не және қолданбаға төлемдерді қалай қосу керек.

Негізгі терминдер

• Соңғы нүкте (endpoint): webhook-тарды қабылдайтын қолданбаңыздағы URL.
• Оқиға / жүктеме (payload): не болғаны және оны сипаттайтын деректер (әдетте JSON).
• Қолтаңба құпиясы (signing secret): қолтаңбаларды тексеруге арналған бөлісілген құпия.
• Идемпотентті: бірдей нәтижемен бірнеше рет орындауға қауіпсіз.
• Polling: webhook күтудің орнына API арқылы өзгерістерді қайта-қайта сұрау.
• Туннель: әзірлеу кезінде webhook-тардың жетуі үшін ноутбукқа уақытша жалпыға ашық URL беретін құрал.

Жиі кездесетін қателер мен қате түсініктер

• Қолтаңбаны тексермеу. Соңғы нүкте URL-ы құпия емес. Растау сұраныстың сенімді екенін қамтамасыз етеді.
• Жауап бермес бұрын баяу жұмыс жасау. Жауап бермес бұрын хат жіберу немесе PDF жасау уақыт асып кетуіне әкеледі, ол қайталауларды тудырады, ал қайталаулар дубликаттарға әкеледі.
• Бір рет, реті бойынша келеді деп ойлау. Оқиға ID-лерін жазып алыңыз және келу ретіне сенбеңіз.
• Алдын ала қарау URL-ын пайдалану. Webhook-тарға тұрақты, жалпыға ашық мекенжай қажет. Жеке алдын ала қарау және localhost интернеттен қолжетімді емес; жарияланған URL-ды пайдаланыңыз (немесе сынау кезінде туннель).
• Тест және тірі құпияларды араластыру. Провайдерлер тест және тірі режимдер үшін әр түрлі қолтаңба құпияларын береді. Екеуін де сақтаңыз және дұрысын пайдаланыңыз.
• Маңызды шешімдерде жүктемеге соқыр сену. Жоғары ставкалы әрекеттер үшін оқиғаны алғаннан кейін провайдердің API-нен соңғы күйді алу орынды.

AI құрастырушыңыздан не сұрау керек

Серверге POST /webhooks/stripe соңғы нүктесін қосыңыз. Stripe қолтаңбасын шикі сұраныс денесі мен STRIPE_WEBHOOK_SECRET құпиясы арқылы тексеріңіз. Жарамсыз қолтаңбаларды 400 арқылы қабылдамаңыз. Әр оқиға ID-ін сақтаңыз және бұрын өңделген оқиғаларды өткізіп жіберіңіз. 200-ді тез қайтарыңыз, содан кейін checkout.session.completed оқиғасын тапсырысты төленді деп белгілеп, түбіртекті жіберу арқылы өңдеңіз. Оқиға түрін журналға жазыңыз. Төлем сәтті беттен қолжетімділік бермеңіз.

Содан кейін сынаңыз: провайдер панелінен тест оқиғасын жіберіңіз, оны қайта жіберіңіз және қате қолтаңбамен сұраныс жіберіңіз. Тек бірінші ғана бірдеңені өзгертуі керек.

Mythex-тегі webhook-тар

Mythex жеке webhook қызметін жүргізбейді; агентке қолданбаңыздың өз backend-іне webhook соңғы нүктесін қосуды сұрайсыз, ал провайдерді жарияланған URL-ға бағыттайсыз, өйткені webhook-тарға жалпыға ашық мекенжай қажет. Қолтаңба құпиясы жоба құпияларыңызға салынады, ал тірі қолданбада оны өзгертсеңіз, қайта жариялайсыз. Webhook-тармен жұмыс құжаттама рецептінде бастапқы сұраныс бар, ал төлем қабылдайтын қолданбалар үшін дүкен үлгілері жақсы бастама.

Сұрақтар