რა არის webhook? როგორ ატყობინებენ აპები ერთმანეთს

Webhook არის ავტომატური შეტყობინება, რომელსაც ერთი სერვისი თქვენს აპს უგზავნის იმ წამს, როცა რამე ხდება. როცა მომხმარებლის გადახდა წარმატებით სრულდება, Stripe აპის მისამართზე webhook-ს აგზავნის შეტყობინებით „გადახდა წარმატებულია, აი დეტალები“, და თქვენი აპი რეაგირებს — ნიშნავს შეკვეთას როგორც გადახდილს, აგზავნის ქვითარს, ხსნის ანგარიშს. მოკლედ: API არის ის, როცა თქვენი აპი სხვა სერვისს კითხვას უსვამს; webhook არის ის, როცა სხვა სერვისი გირეკავთ და გეუბნებათ რამეს.

რატომ არის მნიშვნელოვანი AI-ით აშენებისას

როგორც კი თქვენი აპი გადახდებს იღებს, ფორმის მონაცემებს სხვა ინსტრუმენტიდან იღებს ან GitHub-ის, Shopify-ის თუ კალენდრის მსგავს სერვისებს უკავშირდება, webhook-ებს შეხვდებით. ისინი ჩვეულებრივ სწორი გზაა იმის გასაგებად, რომ რაღაც მოხდა — მაგრამ სწორედ აქ ხდება ხოლმე AI-ით აშენებული აპები ხშირად ფარულად არასწორი:

• ენდფოინთი ნებისმიერ მოთხოვნას იღებს, ასე რომ ვინმეს შეუძლია ყალბი „გადახდა წარმატებულია“ მოვლენა გააგზავნოს.
• აპი წვდომას იძლევა checkout-ის გადამისამართების გვერდზე და არა webhook-ზე, ასე რომ ხალხი, ვინც ადრე დახურავს ჩანართს, იმას ვერ იღებს, რისთვისაც გადაიხადა, ხოლო ვინც წარმატების URL-ს იპოვის, უფასოდ იღებს.
• ერთი და იგივე მოვლენა ორჯერ მოდის და მომხმარებელი ორ შეკვეთას ან ორ წერილს იღებს.

ამ დაცვების გაგება საშუალებას გაძლევთ, წინასწარ მოსთხოვოთ ისინი.

ყოველდღიური ანალოგია: მიწოდების შეტყობინება

შეგიძლიათ გაიგოთ, მოვიდა თუ არა თქვენი ამანათი, ორი გზით. შეგიძლიათ ყოველ ათ წუთში კარებთან გახვიდეთ შესამოწმებლად (ეს არის polling — თქვენი აპი მუდმივად უძახის API-ს კითხვით „არის რამე ახალი?“). ან კურიერმა შეგატყობინოთ SMS-ით, როცა მიიტანს (ეს არის webhook).

SMS აშკარად უკეთესია — სანამ მას შეგიძლიათ ენდოთ. თუ ვინმეს შეეძლო თქვენთვის „ამანათი მიტანილია“ შეტყობინების გაგზავნა, გსურდათ ცოდნა, რომ ის ნამდვილად კურიერისგან მოვიდა. და თუ ტელეფონი გამორთული გქონდათ, როცა შეტყობინება მოვიდა, გსურდათ, რომ კურიერი მოგვიანებით ხელახლა ეცადა. ეს ორი საკითხი — შემოწმება და ხელახალი ცდები — webhook-ებს ართულებს.

როგორ მუშაობს webhook, ნაბიჯ-ნაბიჯ

1. თქვენ ქმნით ენდპოინტს თქვენი აპის ბექენდში: URL-ს, მაგალითად https://yourapp.com/webhooks/stripe, რომელიც POST მოთხოვნებს იღებს.
2. ამ URL-ს პროვაიდერს არეგისტრირებთ და ირჩევთ, რომელ მოვლენებს გსურთ (მაგალითად, „checkout დასრულდა“ და „გამოწერა გაუქმდა“).
3. პროვაიდერი გაძლევთ ხელმოწერის საიდუმლოს. მას სერვერზე საიდუმლოდ ინახავთ — იხილეთ გარემოს ცვლადები და საიდუმლოებები.
4. ხდება მოვლენა. პროვაიდერი თქვენს URL-ზე აგზავნის HTTP მოთხოვნას JSON ტექსტით, რომელიც მოვლენას აღწერს, და ხელმოწერის სათაურით.
5. თქვენი აპი ამოწმებს ხელმოწერას, ინახავს მოვლენის ID-ს, სწრაფად პასუხობს წარმატების კოდით (200), და შემდეგ ასრულებს სამუშაოს.
6. თუ აპი წარმატებით არ უპასუხებს, ბევრი პროვაიდერი მოგვიანებით კვლავ ცდილობს.

ხელმოწერები

ხელმოწერა ადასტურებს, რომ მოთხოვნა პროვაიდერისგან მოვიდა და არ შეცვლილა. მაგალითად, Stripe ითვლის HMAC-ს (გასაღებით დაცულ ანაბეჭდს) SHA-256 ალგორითმით მოთხოვნის სხეულსა და დროის ანაბეჭდზე, ხელმოწერის საიდუმლოს გამოყენებით, და აგზავნის მას Stripe-Signature სათაურში. თქვენი აპი იგივე გამოთვლას აკეთებს თავისი ასლით; თუ შედეგები ემთხვევა, მოთხოვნა ნამდვილია. რადგან დროის ანაბეჭდიც არის ხელმოწერილი, შეგიძლიათ უარყოთ ძველი მოთხოვნები, რომლებიც ვიღაცამ ჩაიწერა და მოგვიანებით ხელახლა გამოაგზავნა — Stripe-ის ბიბლიოთეკები ნაგულისხმევად ხუთი წუთის ტოლერანტობას იყენებენ, დოკუმენტაციის მიხედვით 2026 წლის სექტემბრის მდგომარეობით.

ერთი პრაქტიკული დეტალი: ხელმოწერა გამოითვლება ნედლ (raw) მოთხოვნის სხეულზე. თუ თქვენი ფრეიმვორკი JSON-ს შემოწმებამდე ანალიზს უკეთებს და თავიდან ფორმატირებს, შემოწმება ჩავარდება. ეს ძალიან გავრცელებული შეცდომაა.

ხელახალი ცდები, დუბლიკატები და თანმიმდევრობა

პროვაიდერები განსხვავდებიან, ამიტომ შეამოწმეთ თითოეულის დოკუმენტაცია. 2026 წლის სექტემბრის მდგომარეობით:

Stripe-ის დოკუმენტაცია ასევე ამბობს, რომ მოვლენები არ არის გარანტირებული, რომ მოვლენების მოხვედრის თანმიმდევრობა იმ თანმიმდევრობის ტოლი იქნება, როგორც მოხდა, და რომ იგივე მოვლენა ზოგჯერ ორჯერ შეიძლება მოვიდეს, ამიტომ მოვლენების ID-ების თვალყურის დევნებას გვირჩევს.

ზოგადი გაკვეთილი ნებისმიერი პროვაიდერისთვის ერთია: მოვლენები შეიძლება მოვიდეს დაგვიანებით, ერთზე მეტჯერ და არასწორი თანმიმდევრობით. თქვენმა ჰენდლერმა უნდა იყოს იდემპოტენტური — იმავე მოვლენის ორჯერ დამუშავება იგივე შედეგს იძლევა, რაც ერთხელ დამუშავება.

სამუშაო მაგალითი: ფასიანი კურსის გახსნა

თქვენ კურსს ყიდით ონლაინ. სტუდენტი აჭერს შეძენას, იხდის Stripe-ის ჰოსტირებულ checkout გვერდზე და უბრუნდება თქვენს საიტს.

მყიფე გზა: მადლობის გვერდი კურსს ხსნის. თუ სტუდენტი გადამისამართებისას ბრაუზერს დახურავს, ის გადაიხადა, მაგრამ წვდომა არ აქვს. თუ ვინმე მადლობის გვერდის URL-ს გამოიცნობს, უფასოდ მიიღებს წვდომას.

webhook-ის გზა:

1. როცა Stripe გადახდას ადასტურებს, ის checkout.session.completed მოვლენას აგზავნის /webhooks/stripe-ზე.
2. თქვენი ბექენდი ხელმოწერას ამოწმებს საიდუმლო გასაღებით. თუ ვერ დაამოწმებს, პასუხობს 400-ით და არაფერს აკეთებს.
3. ამოწმებს, მუშავდებოდა თუ არა ეს მოვლენის ID უკვე. თუ დიახ, პასუხობს 200-ით და ჩერდება.
4. ინახავს მოვლენის ID-ს, პასუხობს 200-ით, შემდეგ სტუდენტს აძლევს წვდომას და უგზავნის მისასალმებელ წერილს.
5. მადლობის გვერდი უბრალოდ წერს „გადახდა მიღებულია — თქვენი კურსი მალე გამოჩნდება“ და ამოწმებს სტუდენტის წვდომის სტატუსს.

მოგვიანებით, თუ გამოწერა გაუქმდება ან ბარათი ვერ გაივლის, სხვა webhook-მოვლენები ეუბნება თქვენს აპს, რომ წვდომა მოხსნას ან შეაჩეროს. ასე რჩება გამოწერის პროდუქტები სინქრონში ბილინგთან — იხილეთ რა არის SaaS და როგორ დავამატოთ გადახდები თქვენს აპში.

ძირითადი ტერმინები

• Endpoint (ენდპოინტი): თქვენს აპში არსებული URL, რომელიც webhook-ებს იღებს.
• Event / payload: რა მოხდა და მონაცემები, რომლებიც მას აღწერს (ჩვეულებრივ JSON).
• Signing secret (ხელმოწერის საიდუმლო): საერთო საიდუმლო, რომელიც ხელმოწერების შესამოწმებლად გამოიყენება.
• Idempotent (იდემპოტენტური): უსაფრთხოდ შესრულდება ერთზე მეტჯერ იგივე შედეგით.
• Polling: მუდმივად API-ისთვის ცვლილებების თხოვნა webhook-ის მოლოდინის ნაცვლად.
• Tunnel: ინსტრუმენტი, რომელიც ლეპტოპს დროებით საჯარო URL-ს აძლევს, რათა webhook-ები შეძლებდეს მისვლას განვითარების დროს.

გავრცელებული შეცდომები და მცდარი წარმოდგენები

• ხელმოწერების შემოწმების გარეშე. ენდპოინტის URL არ არის საიდუმლო. შემოწმება არის ის, რაც მოთხოვნას სანდოს ხდის.
• ნელი სამუშაოს შესრულება პასუხამდე. ელფოსტის გაგზავნა ან PDF-ის გენერირება პასუხამდე შეიძლება გამოიწვიოს დროის ამოწურვა, რაც ხელახალ ცდებს იწვევს, რაც დუბლიკატებს.
• ვარაუდი, რომ ზუსტად ერთხელ და თანმიმდევრობით. შეინახეთ მოვლენების ID-ები და არ დაეყრდნოთ მოსვლის თანმიმდევრობას.
• წინასწარი ნახვის URL-ის გამოყენება. Webhook-ებს სჭირდებათ სტაბილური, საჯარო მისამართი. კერძო წინასწარი ნახვები და localhost ინტერნეტიდან არ არის მისაწვდომი; გამოიყენეთ თქვენი გამოქვეყნებული URL (ან tunnel ტესტირებისას).
• სატესტო და live საიდუმლოების აღრევა. პროვაიდერები ხშირად სხვადასხვა ხელმოწერის საიდუმლოს გასცემენ სატესტო და live რეჟიმისთვის. შეინახეთ ორივე და გამოიყენეთ სწორი.
• მნიშვნელოვან გადაწყვეტილებებში მონაცემების ბრმად ნდობა. მაღალი ფსონის მოქმედებებისთვის გონივრულია, რომ მოვლენის მიღების შემდეგ პროვაიდერის API-დან უახლესი მდგომარეობა გამოითხოვოთ.

რას სთხოვოთ თქვენს AI ბილდერს

დაამატე POST /webhooks/stripe ენდპოინტი სერვერზე. შეამოწმე Stripe-ის ხელმოწერა ნედლი მოთხოვნის სხეულით და საიდუმლოთი STRIPE_WEBHOOK_SECRET. არასწორი ხელმოწერები უარყავი 400-ით. შეინახე თითოეული მოვლენის ID და გამოტოვე უკვე დამუშავებული მოვლენები. სწრაფად უპასუხე 200-ით, შემდეგ დაამუშავე checkout.session.completed შეკვეთის გადახდილად მონიშვნით და ქვითრის გაგზავნით. ჩაწერე მოვლენის ტიპი. წვდომა არ მისცე checkout-ის წარმატების გვერდიდან.

შემდეგ შეამოწმეთ: გაგზავნეთ სატესტო მოვლენა პროვაიდერის დაფიდან, გაგზავნეთ იგივე ისევ, და გაგზავნეთ მოთხოვნა არასწორი ხელმოწერით. მხოლოდ პირველმა უნდა შეცვალოს რამე.

Webhook-ები Mythex-ში

Mythex ცალკე webhook სერვისს არ უშვებს; თქვენ აგენტს სთხოვთ, რომ თქვენი აპის საკუთარ ბექენდში webhook ენდპოინტი დაამატოს, და პროვაიდერს მიუთითებთ თქვენს გამოქვეყნებულ URL-ზე, რადგან webhook-ებს საჯარო მისამართი სჭირდებათ. ხელმოწერის საიდუმლო თქვენს პროექტის საიდუმლოებებში მოთავსდება, და თუ მას ცოცხალ აპზე შეცვლით, თავიდან უნდა გამოაქვეყნოთ. დოკუმენტაციის რეცეპტი webhook-ების დამუშავებაზე შეიცავს საწყის მოთხოვნას, ხოლო მაღაზიის შაბლონები კარგი საწყისი წერტილია გადახდების მიმღები აპებისთვის.

კითხვები