وب‌هوک چیست؟ چگونه اپ‌ها یکدیگر را خبر می‌کنند

وب‌هوک (Webhook) پیام خودکاری است که یک سرویس لحظه‌ای که اتفاقی می‌افتد به اپ شما می‌فرستد. وقتی پرداخت مشتری موفق می‌شود، Stripe یک وب‌هوک به نشانی‌ای در اپ شما می‌فرستد که می‌گوید «پرداخت موفق بود، این هم جزئیات»، و اپ شما واکنش نشان می‌دهد — سفارش را پرداخت‌شده علامت می‌زند، رسید می‌فرستد، حساب را فعال می‌کند. به بیان ساده: API یعنی اپ شما از سرویس دیگری سؤال می‌پرسد؛ وب‌هوک یعنی سرویس دیگر اپ شما را صدا می‌زند تا چیزی را خبر دهد.

چرا هنگام ساخت با هوش مصنوعی مهم است

به محض اینکه اپ شما پرداخت می‌گیرد، فرم‌ها را از ابزار دیگری دریافت می‌کند، یا به سرویس‌هایی مثل GitHub، Shopify یا تقویم وصل می‌شود، با وب‌هوک روبه‌رو خواهید شد. معمولاً این روش درست برای فهمیدن این است که اتفاقی افتاده — اما همین‌جاست که اپ‌های ساخته‌شده با هوش مصنوعی اغلب به‌طور ظریفی اشتباه می‌کنند:

• نقطه اتصال هر درخواستی را می‌پذیرد، پس هر کسی می‌تواند رویداد جعلی «پرداخت موفق» بفرستد.
• اپ دسترسی را روی صفحه بازگشت از پرداخت می‌دهد، نه روی وب‌هوک، پس کسانی که زود تب را می‌بندند چیزی را که پرداخت کرده‌اند نمی‌گیرند، و کسانی که نشانی صفحه موفقیت را پیدا می‌کنند رایگان دسترسی می‌گیرند.
• همان رویداد دو بار می‌رسد و مشتری دو سفارش یا دو ایمیل دریافت می‌کند.

دانستن نحوه کار وب‌هوک‌ها به شما کمک می‌کند این محافظت‌ها را از اول درخواست کنید.

یک تشبیه روزمره: پیامک تحویل بسته

می‌توانید دو راه برای فهمیدن رسیدن بسته داشته باشید. می‌توانید هر ده دقیقه تا در جلو بروید و نگاه کنید (این polling است — اپ شما مدام از یک API می‌پرسد «چیز جدیدی هست؟»). یا پیک می‌تواند وقتی بسته تحویل شد برایتان پیامک بفرستد (این یک وب‌هوک است).

پیامک بدون شک بهتر است — به شرطی که بتوانید به آن اعتماد کنید. اگر هر کسی می‌توانست برایتان پیام «بسته تحویل شد» بفرستد، می‌خواستید راهی داشته باشید که مطمئن شوید واقعاً از طرف پیک آمده. و اگر گوشی‌تان خاموش بود وقتی پیامک آمد، می‌خواستید پیک دوباره امتحان کند. این دو موضوع — تأیید و تلاش مجدد — بیشترِ سختی کار با وب‌هوک‌ها هستند.

وب‌هوک گام‌به‌گام چطور کار می‌کند

۱. یک نقطه اتصال بسازید در بک‌اند اپ: نشانی‌ای مثل https://yourapp.com/webhooks/stripe که درخواست‌های POST را می‌پذیرد. ۲. آن نشانی را نزد ارائه‌دهنده ثبت کنید و رویدادهای موردنظر را انتخاب کنید (برای مثال «پرداخت پایان یافت» و «اشتراک لغو شد»). ۳. ارائه‌دهنده یک رمز امضا به شما می‌دهد. آن را به‌عنوان راز در سرورتان ذخیره کنید — ببینید متغیرهای محیطی و رازها. ۴. رویدادی رخ می‌دهد. ارائه‌دهنده یک درخواست HTTP به نشانی شما می‌فرستد، با بدنه JSON که رویداد را شرح می‌دهد، به همراه یک هدر امضا. ۵. اپ شما امضا را تأیید می‌کند، شناسه رویداد را ثبت می‌کند، سریع با کد موفقیت (200) پاسخ می‌دهد و بعد کار را انجام می‌دهد. ۶. اگر اپ شما پاسخ موفقیت ندهد، بسیاری از ارائه‌دهندگان دوباره امتحان می‌کنند.

امضاها

امضا ثابت می‌کند درخواست واقعاً از طرف ارائه‌دهنده آمده و دستکاری نشده است. برای مثال Stripe یک HMAC (نوعی اثرانگشت با کلید، با الگوریتم SHA-256) را روی بدنه درخواست و یک زمان‌نما محاسبه می‌کند، با استفاده از رمز امضا، و آن را در هدر Stripe-Signature می‌فرستد. اپ شما همان محاسبه را با نسخه خودش از رمز انجام می‌دهد؛ اگر نتایج یکی باشد، درخواست معتبر است. از آنجا که زمان‌نما هم امضا شده، می‌توانید درخواست‌های قدیمی‌ای را که کسی ضبط کرده و بعداً دوباره فرستاده رد کنید — کتابخانه‌های Stripe طبق مستنداتش به‌صورت پیش‌فرض یک بازه پنج‌دقیقه‌ای را می‌پذیرند (تا سپتامبر ۲۰۲۶).

یک نکته عملی: امضا روی بدنه خام درخواست محاسبه می‌شود. اگر فریم‌ورک شما JSON را پیش از تأیید تجزیه و دوباره قالب‌بندی کند، بررسی شکست می‌خورد. این یک باگ بسیار رایج است.

تلاش مجدد، تکرار و ترتیب

ارائه‌دهندگان متفاوت‌اند، پس مستندات هر کدام را بررسی کنید. تا سپتامبر ۲۰۲۶:

مستندات Stripe همچنین می‌گوید رویدادها تضمین نشده که به ترتیبی که رخ داده‌اند برسند، و اینکه گاهی ممکن است همان رویداد بیش از یک بار برسد، پس توصیه می‌کند شناسه رویدادها را ثبت کنید.

درس کلی برای هر ارائه‌دهنده همین است: رویدادها ممکن است دیر، بیش از یک بار و نامرتب برسند. کنترل‌کننده شما باید idempotent باشد — پردازش دوباره همان رویداد همان اثری را دارد که پردازش یک بار.

یک مثال کامل: باز کردن دوره پولی

شما یک دوره آنلاین می‌فروشید. دانشجو روی خرید کلیک می‌کند، در صفحه پرداخت میزبانی‌شدهٔ Stripe پرداخت می‌کند، و به سایت شما برمی‌گردد.

راه شکننده: صفحه «متشکرم» دوره را باز می‌کند. اگر دانشجو هنگام بازگشت مرورگر را ببندد، پول داده ولی دسترسی ندارد. و اگر کسی نشانی صفحه تشکر را حدس بزند، بدون پرداخت دسترسی می‌گیرد.

راه وب‌هوک:

۱. وقتی Stripe پرداخت را تأیید کند، رویداد checkout.session.completed را به /webhooks/stripe می‌فرستد. ۲. بک‌اند شما امضا را با رمز امضا تأیید می‌کند. اگر ناموفق بود، با 400 پاسخ می‌دهد و هیچ کاری نمی‌کند. ۳. بررسی می‌کند آیا شناسه آن رویداد قبلاً پردازش شده. اگر بله، با 200 پاسخ می‌دهد و متوقف می‌شود. ۴. شناسه رویداد را ذخیره می‌کند، با 200 پاسخ می‌دهد و سپس دسترسی دانشجو را باز و یک ایمیل خوش‌آمد می‌فرستد. ۵. صفحه «متشکرم» فقط می‌گوید «پرداخت دریافت شد — دوره‌تان به‌زودی ظاهر می‌شود» و وضعیت دسترسی دانشجو را بررسی می‌کند.

بعداً، اگر اشتراکی لغو شود یا کارت شکست بخورد، رویدادهای دیگر وب‌هوک به اپ شما می‌گویند دسترسی را حذف یا تعلیق کند. محصولات اشتراکی این‌طور با صورتحساب هماهنگ می‌مانند — ببینید SaaS چیست و نحوه افزودن پرداخت به اپ.

اصطلاحات کلیدی

• Endpoint (نقطه اتصال): نشانی در اپ شما که وب‌هوک‌ها را دریافت می‌کند.
• Event / payload (رویداد / بار داده): آنچه رخ داده و داده‌ای که آن را شرح می‌دهد (معمولاً JSON).
• Signing secret (رمز امضا): رمز مشترکی که برای تأیید امضاها استفاده می‌شود.
• Idempotent (ایدمپوتنت): امن برای اجرای بیش از یک بار با نتیجه یکسان.
• Polling (نظرسنجی مداوم): پرسیدن مکرر از یک API برای تغییرات، به‌جای منتظر ماندن برای وب‌هوک.
• Tunnel (تونل): ابزاری که به یک لپ‌تاپ نشانی عمومی موقت می‌دهد تا وب‌هوک‌ها در زمان توسعه به آن برسند.

اشتباهات رایج و باورهای غلط

• تأیید نکردن امضاها. نشانی نقطه اتصال رمز نیست. تأیید است که درخواست را قابل اعتماد می‌کند.
• انجام کار کند پیش از پاسخ. فرستادن ایمیل یا ساختن PDF قبل از پاسخ می‌تواند باعث timeout شود، که تلاش مجدد را فعال می‌کند، که تکرار را پدید می‌آورد.
• فرض کردن یک‌بار دقیقاً و به ترتیب. شناسه رویدادها را ثبت کنید و به ترتیب رسیدن تکیه نکنید.
• استفاده از نشانی پیش‌نمایش. وب‌هوک‌ها به نشانی ثابت و عمومی نیاز دارند. پیش‌نمایش‌های خصوصی و localhost از اینترنت قابل دسترسی نیستند؛ از نشانی منتشرشده‌تان استفاده کنید (یا هنگام آزمایش از یک تونل).
• مخلوط کردن رمزهای آزمایشی و زنده. ارائه‌دهندگان اغلب برای حالت‌های تست و زنده رمزهای امضای متفاوت می‌دهند. هر دو را ذخیره کنید و درست را به کار ببرید.
• اعتماد کورکورانه به بار داده برای تصمیم‌های مهم. برای کارهای پرریسک، منطقی است بعد از دریافت رویداد آخرین وضعیت را از API ارائه‌دهنده بگیرید.

چه چیزی از سازنده هوش مصنوعی بخواهید

یک نقطه اتصال POST /webhooks/stripe در سرور اضافه کن. امضای Stripe را با استفاده از بدنه خام درخواست و رمز STRIPE_WEBHOOK_SECRET تأیید کن. امضاهای نامعتبر را با 400 رد کن. شناسه هر رویداد را ذخیره کن و رویدادهای پردازش‌شده را رد کن. سریع با 200 پاسخ بده، سپس checkout.session.completed را با علامت‌گذاری سفارش به‌عنوان پرداخت‌شده و ارسال رسید مدیریت کن. نوع رویداد را ثبت کن. دسترسی را از صفحه موفقیت پرداخت نده.

سپس آن را آزمایش کنید: یک رویداد آزمایشی از داشبورد ارائه‌دهنده بفرستید، همان را دوباره بفرستید، و یک درخواست با امضای اشتباه بفرستید. فقط اولی باید چیزی را تغییر دهد.

وب‌هوک‌ها در Mythex

Mythex سرویس جداگانه‌ای برای وب‌هوک ندارد؛ از ایجنت می‌خواهید یک نقطه اتصال وب‌هوک در بک‌اند خود اپ اضافه کند، و ارائه‌دهنده را به نشانی منتشرشده شما وصل می‌کنید، چون وب‌هوک‌ها به نشانی عمومی نیاز دارند. رمز امضا در رازهای پروژه شما قرار می‌گیرد، و اگر آن را روی یک اپ زنده تغییر دهید، دوباره منتشر کنید. دستور آماده مستندات برای مدیریت وب‌هوک‌ها یک پرامپت آغازین دارد، و قالب‌های فروشگاه نقطه شروع خوبی برای اپ‌هایی هستند که پرداخت می‌گیرند.

پرسش‌ها