وب‌هوک چیست؟ اعلان خودکار بین سایت، درگاه و نرم‌افزار

اگر می‌پرسید وب‌هوک چیست، پاسخ کوتاه این است: اعلان خودکار از یک سامانه به سامانهٔ دیگر وقتی رویدادی رخ می‌دهد — نه اینکه شما هر چند دقیقه بروید و بپرسید «حالا چه شد؟». درگاه پرداخت بعد از تأیید، به آدرس شما پیام می‌زند. فروشگاه بعد از ثبت سفارش، CRM را خبر می‌کند. پیامک وقتی ارسال می‌شود که رکورد پایدار شده باشد. وب‌هوک دکمهٔ جادویی نیست؛ قراردادی است برای «چه کسی، چه وقتی، چه داده‌ای، با چه امضایی» به شما خبر بدهد.

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

Webhooks are a way for one application to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.

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

وب‌هوک یک درخواست HTTP است که فرستنده بعد از رویداد به آدرسی که شما داده‌اید می‌فرستد. بدنه معمولاً JSON است: شناسهٔ سفارش، وضعیت پرداخت، زمان، و گاهی دادهٔ کاربر. گیرنده باید پاسخ سریع بدهد — اغلب 2xx — و کار سنگین را به صف بسپارد. اگر پاسخ دیر شود، فرستنده ممکن است دوباره بفرستد. اگر پاسخ خطا باشد، معمولاً تلاش مجدد می‌کند. بنابراین گیرنده باید فرض کند پیام ممکن است دو بار برسد.

این مدل برای کارهایی است که «الان» مهم‌اند: پرداخت تأیید شد، موجودی برگشت، نوبت لغو شد. برای گزارش شبانه یا همگام‌سازی کاتالوگ کامل، درخواست دوره‌ای یا صف داخلی ممکن است ساده‌تر باشد. وب‌هوک را برای هر فیلدی که عوض می‌شود روشن نکنید؛ نویز و هزینهٔ خطا بالا می‌رود. یک فهرست کوتاه رویدادهای حیاتی بهتر از ده‌ها اعلان تزئینی است.

آدرس گیرنده باید عمومی، HTTPS، و تحت کنترل شما باشد. دامنهٔ شخصی یک برنامه‌نویس یا سرویس آزمایشی رایگان، نقطهٔ شکست است. محیط تست را از تولید جدا کنید تا پرداخت آزمایشی به مشتری واقعی پیامک نزند. مالکیت این آدرس را در قرارداد و مستند بنویسید؛ جزئیات مالکیت اتصال را در مقالهٔ یکپارچه‌سازی دنبال کنید تا این صفحه روی خودِ رویداد بماند. اگر تیم چند نفره است، دو نفر باید بتوانند آدرس را در پنل درگاه پیدا کنند و یک رویداد آزمایشی بفرستند؛ وگرنه دانش اتصال فردی است نه سازمانی.

بدنه را بیش از نیاز بزرگ نکنید. شناسه، نوع رویداد، زمان و وضعیت معمولاً کافی است. کپی کامل شیء کاربر با فیلدهای حساس، سطح حمله را بالا می‌برد و لاگ را خطرناک می‌کند. نسخه‌ای از قرارداد رویداد بنویسید تا وقتی درگاه فیلد اضافه کرد، گیرنده غافلگیر نشود. همان قرارداد را در تست تکرار کنید: یک پیام نمونه، یک امضای نمونه، یک پاسخ مورد انتظار. بدون این سه قطعه، «در تولید درست می‌شود» فقط امید است.

تفاوت وب‌هوک با API معمولی چیست؟

API معمولی را شما شروع می‌کنید: موجودی را می‌گیرید، سفارش می‌سازید، وضعیت را می‌پرسید. وب‌هوک را طرف مقابل شروع می‌کند وقتی چیزی عوض شده. اگر فقط API دوره‌ای داشته باشید، بین دو پرسش ممکن است پرداخت آمده باشد و سایت هنوز «در انتظار» نشان بدهد. اگر فقط وب‌هوک داشته باشید و یک پیام گم شود، تا ابد همان وضعیت غلط می‌ماند مگر استعلام دستی یا زمان‌بندی جبرانی داشته باشید.

Polling یعنی شما هر دقیقه بپرسید. برای تعداد کم و تأخیر قابل قبول، ساده است. برای پرداخت لحظه‌ای، هم دیر است هم به نرخ درخواست درگاه فشار می‌آورد. وب‌هوک تأخیر را کم می‌کند اما مسئولیت امضا، تکرار و صف را به شما می‌دهد. انتخاب را از حساسیت رویداد بگیرید نه از مد فنی. جزئیات طراحی endpoint را در مقالهٔ API بخوانید؛ اینجا مرز «چه کسی شروع می‌کند» مهم است تا دو URL یک نیت نشوند.

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

پرداخت و سفارش را چطور با وب‌هوک وصل کنیم؟

پرداخت حساس‌ترین نمونه است. باید معلوم باشد کدام سیستم «پرداخت شده» را اعلام می‌کند. وب‌هوک نقطهٔ شروع است، استعلام نقطهٔ اطمینان. وضعیت‌های میانی — در انتظار، ناموفق، برگشت — را در مدل داده بگذارید. اگر فقط موفق و ناموفق دارید، پیام ناقص شما را گیج می‌کند. مبلغ را از پیام وب‌هوک به‌تنهایی به عنوان حقیقت حسابداری نپذیرید مگر با استعلام و شناسهٔ پایدار جور باشد. تعرفه در این مقاله نمی‌آید؛ منطق وضعیت مهم است.

سفارش باید قبل از پیامک پایدار شود. اگر وب‌هوک «ثبت شد» آمد ولی تراکنش دیتابیس شما rollback شد، مشتری پیام موفقیت می‌گیرد و پنل خالی است. ترتیب را این‌طور بچینید: ذخیرهٔ پایدار، بعد اعلان خروجی. برای کلینیک همین منطق روی نوبت است: ظرفیت را قفل کنید، بعد پیامک یادآوری. دیده شدن مطب در گوگل نیت جداست؛ آن را در سئو سایت پزشکی نگه دارید و این صفحه را برای اعلان رویداد.

شناسهٔ رویداد را ذخیره کنید تا پیام تکراری دوباره موجودی کم نکند. اگر درگاه همان پرداخت را دو بار بفرستد، بار دوم باید «قبلاً اعمال شد» باشد نه خطای جدید و نه کم کردن دوباره. این همان idempotency است که در اتصال سیستم‌ها هم گفتیم. بدون آن، پشتیبانی غرق در سفارش‌های دوتایی می‌شود.

امنیت امضا و احراز پیام یعنی چه؟

هر کسی که آدرس وب‌هوک شما را حدس بزند نباید بتواند «پرداخت شد» جعل کند. فرستنده‌های معتبر معمولاً یک امضا با کلید مشترک روی بدنه می‌گذارند. شما امضا را با همان کلید بررسی می‌کنید و اگر نخواند، 4xx می‌دهید و هیچ وضعیتی را عوض نمی‌کنید. کلید را در سرور نگه دارید نه در فرانت و نه در مخزن عمومی. چرخش کلید را در تقویم نگهداری بگذارید.

HTTPS اجباری است. بدنه را قبل از بررسی امضا parse نکنید اگر مستند فرستنده می‌گوید روی بایت خام امضا شده. محدودیت نرخ و فهرست IP در صورت پشتیبانی درگاه کمک است اما جایگزین امضا نیست. لاگ را بدون دادهٔ کارت و بدون توکن بنویسید. محیط تست را با کلید جدا و درگاه سندباکس نگه دارید.

دسترسی داخلی را هم محدود کنید. پنل نباید به هر کارمند اجازهٔ عوض کردن آدرس وب‌هوک بدهد. تغییر آدرس باید ثبت شود: چه کسی، چه زمانی. اگر اتصال روی اسکریپت شخصی یک نفر باشد، قطع همکاری سیستم را می‌خواباند. مالکیت کلید و آدرس را مثل کد در قرارداد ببینید. بعد از حادثه، بدون لاگ امضای نامعتبر نمی‌فهمید حمله بوده یا پیکربندی غلط. هشدار روزانهٔ «چند پیام رد شد» از یک نمودار زیبا برای امنیت عملیاتی مفیدتر است.

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

خطا، تکرار پیام و تلاش مجدد را چطور طراحی کنیم؟

فرستنده معمولاً چند بار تلاش می‌کند اگر شما 5xx بدهید یا timeout کنید. اگر کار را هم‌زمان با پاسخ HTTP انجام دهید و بعد از موفقیت نیمه‌کاره خطا بدهید، ممکن است دوباره همان رویداد بیاید. الگوی سالم: پیام را سریع بپذیرید، در صف بگذارید، بعد پردازش کنید، و با شناسه از تکرار جلوگیری کنید. اگر پردازش شکست خورد، خودتان retry کنترل‌شده داشته باشید نه اینکه به فرستنده وابسته شوید.

هشدار بگذارید: صف گیر کرده، نرخ امضای نامعتبر بالا، یا پرداخت بدون سفارش. گزارش صبحگاهی «رویدادهای معلق» برای عملیات قابل اقدام است. تیمی که فقط در تولید می‌فهمد وب‌هوک عوض شده، همیشه غافلگیر می‌شود. تست قراردادی بعد از هر تغییر درگاه اجباری باشد: یک سفارش آزمایشی از ثبت تا اعلان. اگر درگاه سندباکس دارد، همان مسیر را در محیط تست هفته‌ای یک‌بار تکرار کنید حتی وقتی کدی عوض نشده؛ گواهی و محدودیت نرخ بی‌خبر عوض می‌شوند.

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

نسخهٔ اول اتصال را مثل حداقل محصول قابل عرضه کوچک بگیرید: یک رویداد، دو سیستم، گزارش اختلاف. همهٔ وب‌هوک‌های ممکن را در هفتهٔ اول روشن نکنید. ظرفیت نگهداری تیم کوچک محدود است.

اشتباهات رایج در پیاده‌سازی وب‌هوک

• قبول پیام بدون بررسی امضا
• کم کردن موجودی در هر بار دریافت بدون شناسهٔ پایدار
• پیامک قبل از تثبیت رکورد
• آدرس روی دامنه یا لپ‌تاپ شخصی
• اتکا فقط به وب‌هوک بدون استعلام برای پرداخت
• پردازش سنگین داخل همان درخواست HTTP
• لاگ حاوی دادهٔ حساس

کانکتور آماده ممکن است برای مسیر استاندارد کافی باشد. وقتی قانون فروش شما غیرعادی است، گیرندهٔ کنترل‌شده لازم می‌شود. انتخاب را از فرآیند بگیرید. اگر هنوز نمی‌دانید سفارش کجا متولد می‌شود، وب‌هوک فقط همان ابهام را سریع‌تر پخش می‌کند. قبل از روشن کردن تولید، یک بار با تیم فروش و پشتیبانی مسیر یک سفارش مشکل‌دار را روی کاغذ بکشید؛ همان جا می‌فهمید کدام رویداد واقعاً لازم است.

مستند کوتاه برای پشتیبانی بنویسید: اگر وضعیت پرداخت با پنل درگاه نخواند، اول شناسه را در لاگ پیدا کنید، بعد استعلام کنید، بعد دستی اصلاح نکنید مگر با ثبت دلیل. بدون این دستور، هر حادثه به چت خصوصی و تصمیم متناقض می‌رسد. وب‌هوک زیرساخت اعتماد عملیات است نه فقط کار برنامه‌نویس.

چک‌لیست قبل از روشن کردن وب‌هوک تولید

1. رویدادهای حیاتی فهرست شده‌اند، نه همهٔ رویدادهای ممکن.
2. آدرس HTTPS و مالکیت آن مشخص است.
3. امضا بررسی می‌شود و کلید از محیط تولید جداست.
4. شناسهٔ رویداد ذخیره می‌شود تا تکرار بی‌اثر باشد.
5. برای پرداخت، استعلام مکمل تعریف شده است.
6. صف و هشدار برای شکست پردازش وجود دارد.
7. محیط تست به مشتری واقعی اعلان نمی‌فرستد.
8. یک سفارش آزمایشی از ثبت تا اعلان مستند شده است.

جمع‌بندی: خبر رویداد، با امضا و بدون تکرار مخرب

وب‌هوک چیست؟ اعلان خودکار وقتی چیزی در سامانهٔ دیگر رخ داده است. با API معمولی فرق دارد چون شما شروع‌کننده نیستید. برای پرداخت و سفارش، اعلان به‌علاوهٔ استعلام لازم است. امضا جلوی جعل را می‌گیرد. صف و شناسه جلوی تکرار مخرب را می‌گیرند. آدرس و کلید باید دارایی سازمان باشند نه فرد.

برای طراحی گیرندهٔ رویداد روی سامانهٔ واقعی، صفحه توسعه نرم‌افزار سفارشی روبینش و فرم مشاوره نقطهٔ شروع‌اند. اول یک رویداد را تا ته ایمن کنید، بعد فهرست را بزرگ کنید. تعداد وب‌هوک معیار موفقیت نیست؛ صحت وضعیت هست.