Webhook: وقتی سرویس‌ها به تو خبر می‌دهند

به‌جای پرسیدن مداوم، بگذار سرویس خبر بدهد؛ امضای Webhook را بررسی کن، تحویل تکراری را بشناس، سریع پاسخ بده و کار سنگین را بعد انجام بده.

بعد از این درس می‌توانی

  • تفاوت Webhook و پرسیدن دوره‌ای (polling) را بگوید و برای یک کار، یکی را با دلیل انتخاب کند.
  • توضیح بدهد امضای HMAC چطور ثابت می‌کند پیام از فرستنده واقعی آمده و دست نخورده است، و چرا مقایسه باید زمان‌ثابت باشد.
  • گیرنده‌ای طراحی کند که تحویل تکراری را با شناسه رویداد تشخیص بدهد و پردازش را دوباره انجام ندهد.
  • ترتیب کارهای گیرنده (بررسی، تأیید سریع، پردازش بعدی) و خطرهای اعتماد به محتوای Webhook را بنویسد.

چرا این درس مهم است

برگ سبز می‌خواست وقتی سفارشی ارسال شد، به مشتری پیام بدهد. نسخه اول ورک‌فلو هر دقیقه از سامانه سفارش می‌پرسید «چیز تازه‌ای ارسال شده؟»؛ روزی ۱۴۴۰ درخواست که بیشترشان جواب «نه» داشتند، و تا یک دقیقه تأخیر. نسخه دوم Webhook بود: سامانه سفارش خودش خبر می‌داد. سریع و کم‌هزینه. تا روزی که کسی نشانی Webhook را پیدا کرد و رویداد ساختگی «سفارش ارسال شد» فرستاد، و روز دیگری که سامانه یک رویداد را سه بار تحویل داد و مشتری سه پیام گرفت.

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

مفاهیم کلیدی

یادآوری: ماشه را در طرح خودکارسازی دوره پایه دیدی؛ ایدمپوتنت و کلید ایدمپوتنسی را در درس‌های اول و چهارم همین دوره.

  • Webhook (وب‌هوک): درخواست HTTP که یک سرویس، هنگام رخ دادن رویدادی، خودش به نشانی تو می‌فرستد.
  • Polling (پرسیدن دوره‌ای): پرسیدن منظم از یک سرویس که «چیز تازه‌ای هست؟».
  • Payload (محموله): بدنه درخواست Webhook که اطلاعات رویداد را دارد.
  • HMAC Signature (امضای HMAC): کدی که فرستنده از محموله و یک راز مشترک می‌سازد تا گیرنده بفهمد پیام از او آمده و دست نخورده است.
  • Constant-time Comparison (مقایسه زمان‌ثابت): مقایسه‌ای که زمانش به محل اولین اختلاف بستگی ندارد تا از زمان پاسخ نشود امضا را حدس زد.
  • Duplicate Delivery (تحویل تکراری): رسیدن دوباره همان رویداد به گیرنده؛ رفتار عادی بسیاری از فرستنده‌ها پس از تأخیر یا خطا.

مدل ذهنی

Polling مثل این است که هر ده دقیقه به پستخانه زنگ بزنی «بسته‌ام رسید؟». Webhook مثل این است که پستچی خودش زنگ در را بزند. راحت‌تر است، ولی حالا هر کسی می‌تواند زنگ در را بزند و بگوید «پستچی‌ام». پس: کارت شناسایی را نگاه کن (امضا)، اگر همان بسته را دوباره آورد دو بار تحویل نگیر (شناسه رویداد)، و رسید را سریع امضا کن و بسته را بعداً باز کن (پاسخ سریع، پردازش بعدی).

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

مسیر یک Webhook از فرستنده تا پردازش

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

گام‌به‌گام

گام ۱: Webhook یا Polling؟

معیارWebhookPolling
تأخیرتقریباً فوریتا فاصله پرسیدن
تعداد درخواستفقط وقتی رویدادی هستثابت، حتی وقتی خبری نیست
نیازنشانی عمومی در دسترس فرستندهفقط دسترسی به API
ریسکپیام جعلی، تحویل تکراری، از دست رفتن وقتی گیرنده خاموش استمحدودیت نرخ، هدر رفتن درخواست
کیسرویس Webhook دارد و تأخیر مهم استسرویس Webhook ندارد، یا گیرنده نمی‌تواند عمومی باشد

در عمل، بسیاری از سامانه‌ها هر دو را دارند: Webhook برای سرعت، و یک Polling کم‌تکرار (مثلاً روزانه) برای پیدا کردن رویدادهایی که وقتی گیرنده خاموش بود از دست رفتند.

گام ۲: امضا را روی بدنه خام بررسی کن

روشی که GitHub و بسیاری از سرویس‌ها به کار می‌برند: فرستنده با یک راز مشترک از بدنه کد HMAC-SHA256 می‌سازد و در هدر می‌فرستد؛ در GitHub هدر X-Hub-Signature-256 با مقدار sha256= و کد هگز استsrc-github-webhook-validation. گیرنده همان محاسبه را با راز خودش انجام می‌دهد و دو مقدار را مقایسه می‌کند. نام هدر و قالب بین سرویس‌ها فرق دارد؛ مستندات هر سرویس را ببین. گیرنده آزمایشی این درس هدر X-Signature-256 را انتظار دارد.

سه نکته که اشتباه رایج‌اند:

  • روی بدنه خام، پیش از تجزیه JSON. تجزیه و دوباره ساختن JSON ممکن است فاصله‌ها یا ترتیب را عوض کند و امضا دیگر نخواند.
  • مقایسه زمان‌ثابت. GitHub صریحاً می‌گوید از عملگر == ساده استفاده نکن و تابع مقایسه زمان‌ثابت (در Python hmac.compare_digest) به کار ببرsrc-github-webhook-validation.
  • راز را مثل کلید نگه دار: تصادفی و طولانی، در جای امن، هرگز در کد یا مخزنsrc-github-webhook-validation.

گام ۳: تحویل تکراری عادی است

فرستنده‌ها وقتی پاسخ سریع نگیرند یا خطای شبکه ببینند، دوباره می‌فرستند. پس گیرنده باید فرض کند هر رویداد ممکن است بیش از یک بار برسد. همان منطق کلید ایدمپوتنسی درس قبل، این بار سمت گیرنده: شناسه رویداد (اگر فرستنده می‌دهد) یا ترکیبی یکتا از محموله را ثبت کن و رویداد تکراری را تأیید کن ولی پردازش نکن. هدف این است که پردازش رویداد، از نظر اثر، ایدمپوتنت باشدsrc-mdn-idempotent.

ثبت شناسه‌ها باید ماندگار باشد (پایگاه داده یا جدول)، نه در حافظه؛ وگرنه با راه‌اندازی دوباره گیرنده فراموش می‌شود.

گام ۴: ترتیب کار گیرنده

  1. مسیر و نوع محتوا و اندازه بدنه را بررسی کن.
  2. امضا را روی بدنه خام بررسی کن؛ نادرست ← 401 و هیچ کار دیگر.
  3. JSON را تجزیه کن و شناسه رویداد را بخوان.
  4. اگر تکراری است ← 200 بدون پردازش.
  5. شناسه را ثبت کن و سریع 200 بده.
  6. کار سنگین (فراخوانی API دیگر یا مدل، ارسال پیام) را بعداً انجام بده؛ در ابزارهای ورک‌فلو یعنی پاسخ دادن پیش از گام‌های کند یا سپردن به ورک‌فلوی دیگر.

گام ۵: به محتوا اعتماد کامل نکن

امضای درست یعنی پیام از فرستنده آمده؛ نه اینکه محتوایش برای هر کاری مناسب است. اگر Webhook از پیام‌رسان یا فرم می‌آید، متن آن را کاربر نوشته و ممکن است دستورهای پنهان برای مدل زبانی داشته باشد (تزریق پرامپت در دوره پایه). و اگر کار مهمی بر اساس رویداد انجام می‌دهی (مثل بازپرداخت)، وضعیت را دوباره از API اصلی بخوان، به‌جای تکیه کامل بر محموله.

مثال‌ها

پیاده‌سازی عملی

گیرنده امن در برابر پنج نوع رویداد. حدود ۲۰ دقیقه.

اجرای محلی

دو پنجره باز کن و در هر دو یک مقدار تمرینی برای راز بگذار (در PowerShell: $env:WEBHOOK_SECRET = "practice-secret-change-me"):

export WEBHOOK_SECRET=practice-secret-change-me
python webhook_receiver.py

در پنجره دوم با assets/send_webhook.py پنج حالت را بفرست:

export WEBHOOK_SECRET=practice-secret-change-me
python send_webhook.py good
python send_webhook.py duplicate
python send_webhook.py tampered
python send_webhook.py unsigned
python send_webhook.py wrongsecret

برای هر حالت بنویس گیرنده چه کرد و چرا. بعد در assets/webhook_receiver.py خط seen_events.add(eid) را موقتاً حذف کن، گیرنده را دوباره اجرا کن و duplicate را بفرست: چند بار «processing» می‌بینی؟ تغییر را برگردان.

بدون اجرا / شبیه‌ساز

assets/sample-run.txt خروجی همین پنج حالت را دارد. برای هر حالت بنویس گیرنده در کدام گام (بند ۱ تا ۶ گام ۴) تصمیم گرفت. بعد کد assets/webhook_receiver.py را بخوان و جای هر گام را در کد پیدا کن.

بدون کد

برای یک ورک‌فلوی بدون کد با ماشه Webhook (مثلاً پیام تازه در پیام‌رسان یا فرم پرشده)، شش گام گام ۴ را به ترتیب گره‌ها بنویس: کدام گره امضا یا راز را بررسی می‌کند، شناسه رویداد کجا ثبت می‌شود (جدول یا پایگاه داده)، و ورک‌فلو کجا پاسخ می‌دهد.

با کد

گیرنده را طوری تغییر بده که رویدادهای قدیمی‌تر از ۱۰ دقیقه را (بر اساس created_at محموله) رد کند و توضیح بده چرا این کار به‌تنهایی امنیت نمی‌آورد مگر اینکه زمان هم جزو بخش امضاشده باشد.

اشتباه‌های رایج

اشتباهنتیجهکار درست
گیرنده بدون بررسی امضاهر کس نشانی را بداند رویداد جعلی می‌فرستدامضا پیش از هر کار
بررسی امضا پس از تجزیه و ساختن دوباره JSONامضای درست هم رد می‌شودروی بدنه خام
مقایسه با ==نشت اطلاعات از زمان پاسخمقایسه زمان‌ثابت
پردازش هر تحویلپیام یا اقدام تکراریثبت ماندگار شناسه رویداد
کار سنگین پیش از پاسخفرستنده دوباره می‌فرستدپاسخ سریع، پردازش بعدی
اعتماد کامل به محموله برای اقدام مهمتصمیم بر اساس داده دستکاری‌شده یا کهنهوضعیت را از API اصلی دوباره بخوان
راز Webhook در کدنشت راز یعنی امکان جعلمثل کلید API نگه دار

اشکال‌زدایی

همه رویدادهای واقعی با «bad signature» رد می‌شوند.

امضا روی JSON تجزیه‌شده و دوباره‌ساخته محاسبه می‌شود، یا راز دو طرف یکی نیست، یا کدگذاری متن فرق دارد.

امضا را روی بایت‌های خام دریافتی محاسبه کن؛ راز را (بدون چاپ مقدارش) با مقدار تنظیم‌شده در فرستنده مقایسه کن.

بدنه خام و راز یکسان؛ متن را UTF-8 در نظر بگیر.

مشتری برای یک رویداد سه پیام گرفته است.

فرستنده رویداد را سه بار تحویل داده و گیرنده هر بار پردازش کرده است؛ احتمالاً چون گیرنده دیر پاسخ می‌داد.

شناسه رویداد را در لاگ جست‌وجو کن؛ زمان پاسخ گیرنده را ببین.

ثبت ماندگار شناسه و رد پردازش تکراری؛ پاسخ پیش از کار سنگین.

پس از خاموشی چندساعته گیرنده، چند سفارش هرگز پیام ارسال نگرفتند.

فرستنده پس از چند تلاش ناموفق دست کشید و رویدادها از دست رفتند.

فهرست سفارش‌های ارسال‌شده در آن بازه را با رویدادهای ثبت‌شده مقایسه کن.

یک Polling کم‌تکرار برای پیدا کردن رویدادهای جاافتاده؛ و هشدار وقتی گیرنده در دسترس نیست.

نکته‌های امنیتی

تمرین کوتاه

تمرین · 10 دقیقه

هدف: انتخاب Webhook یا Polling.

گام‌ها: برای هر مورد یکی را انتخاب کن و یک دلیل بنویس.

  1. پیام تازه در ربات پیام‌رسان پشتیبانی.
  2. گزارش فروش روزانه از سامانه‌ای که Webhook ندارد.
  3. تأیید پرداخت از درگاه پرداخت که Webhook امضاشده دارد.
  4. ورک‌فلویی روی لپ‌تاپ شخصی بدون نشانی عمومی که باید ایمیل‌های تازه را بخواند.

معیار پذیرش: ۱ و ۳ Webhook؛ ۲ و ۴ Polling؛ برای ۳ اشاره به بررسی امضا و دوباره‌خوانی وضعیت از API اصلی.

راه‌حل نمونه

۱: Webhook؛ تأخیر مهم است و رویدادها نامنظم‌اند. ۲: Polling روزانه؛ سرویس Webhook ندارد و تأخیر مهم نیست. ۳: Webhook با بررسی امضا، و پیش از تحویل سفارش وضعیت پرداخت را از API درگاه دوباره بخوان؛ به‌علاوه Polling کم‌تکرار برای رویدادهای جاافتاده. ۴: Polling؛ گیرنده عمومی نیست و فرستنده نمی‌تواند به آن برسد.

چالش

تمرین · 30 دقیقه

موقعیت: در طرح خودکارسازی کار خودت، ماشه‌ها را بررسی کن. برای هر ماشه‌ای که رویداد بیرونی است، طرح گیرنده بنویس. اگر سرویس واقعی و داده‌اش حساس است، رویداد نمونه را ساختگی یا ناشناس بساز.

  1. برای هر ماشه: Webhook یا Polling، با دلیل؛ و اگر Webhook، آیا فرستنده امضا می‌دهد؟
  2. یک محموله نمونه بنویس و شناسه رویداد را مشخص کن (اگر نیست، چطور شناسه یکتا می‌سازی).
  3. شش گام گیرنده را برای این ماشه بنویس: بررسی‌ها، کجا شناسه ثبت می‌شود، کی پاسخ می‌دهد، کار سنگین کجا می‌رود.
  4. برای رویدادهای جاافتاده (گیرنده خاموش بود) راه جبران بنویس.

خروجی مورد انتظار: جدول ماشه‌ها با انتخاب و دلیل، محموله نمونه، طرح شش‌گامی گیرنده و راه جبران.

معیار پذیرش:

  • گیرنده Webhook بدون بررسی امضا (یا دلیل روشن و جبران) نیست.
  • تحویل تکراری با ثبت ماندگار شناسه مدیریت می‌شود.
  • پاسخ پیش از کار سنگین است.
  • محموله نمونه ساختگی یا ناشناس است و هیچ راز واقعی در طرح نیست.

پرسش‌های سنجش

جمع‌بندی

  • Webhook یعنی سرویس خودش خبر می‌دهد؛ Polling یعنی تو می‌پرسی. Webhook سریع‌تر است ولی گیرنده عمومی و امن می‌خواهد.
  • امضای HMAC را روی بدنه خام با راز مشترک و مقایسه زمان‌ثابت بررسی کن؛ نشانی Webhook راز نیست.
  • تحویل تکراری عادی است؛ شناسه رویداد را ماندگار ثبت کن و تکراری را تأیید کن ولی پردازش نکن.
  • سریع پاسخ بده و کار سنگین را بعد انجام بده.
  • امضای درست یعنی فرستنده واقعی، نه محتوای قابل اعتماد؛ برای اقدام مهم وضعیت را از API اصلی بخوان.
  • برای رویدادهای جاافتاده، Polling کم‌تکرار و هشدار خاموشی گیرنده.

پرسش‌های سنجش

ورک‌فلوی برگ سبز هر دقیقه از سامانه سفارش می‌پرسد «سفارش ارسال‌شده تازه؟». سامانه حالا Webhook امضاشده دارد. آیا Polling را کامل حذف می‌کنی؟ تصمیم و دلیلت را بنویس.

پاسخ نمونه و معیار ارزیابی

Webhook را ماشه اصلی می‌کنم چون فوری است و درخواست بی‌فایده نمی‌سازد. Polling را کامل حذف نمی‌کنم؛ آن را به فاصله کم‌تکرار (مثلاً روزانه) می‌برم تا رویدادهایی که هنگام خاموشی یا خطای گیرنده از دست رفته‌اند پیدا شوند، و با ثبت شناسه از پردازش دوباره جلوگیری می‌کنم.

  • Webhook را ماشه اصلی با دلیل (1 امتیاز)
  • Polling کم‌تکرار برای رویدادهای جاافتاده (1 امتیاز)
  • جلوگیری از پردازش دوباره بین دو مسیر (1 امتیاز)
  • Polling را کامل حذف کن ← اگر گیرنده چند ساعت خاموش باشد، رویدادها ممکن است برای همیشه از دست بروند.

همکارت می‌گوید: «نشانی Webhook ما طولانی و تصادفی است، کسی پیدایش نمی‌کند؛ بررسی امضا لازم نیست.» به او بگو امضای HMAC دقیقاً چه چیزی را ثابت می‌کند که نشانی پنهان ثابت نمی‌کند، و چرا مقایسه امضا باید زمان‌ثابت باشد.

پاسخ نمونه و معیار ارزیابی

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

  • منشأ (داشتن راز) و دست‌نخوردن بدنه (1 امتیاز)
  • نشانی پنهان امنیت نیست (1 امتیاز)
  • دلیل مقایسه زمان‌ثابت (1 امتیاز)
  • HTTPS کافی است ← HTTPS مسیر را رمز می‌کند ولی نمی‌گوید چه کسی فرستاده است.

گیرنده Webhook پس از هر به‌روزرسانی نرم‌افزار، برای چند رویداد پیام تکراری به مشتری می‌فرستد. کد گیرنده شناسه رویداد را بررسی می‌کند. علت محتمل و اصلاح چیست؟

بخشی از کد گیرنده.

seen_events = set()
...
if eid in seen_events:
    return reply(200, "duplicate")
seen_events.add(eid)
پاسخ نمونه و معیار ارزیابی

شناسه‌ها فقط در حافظه نگه داشته می‌شوند؛ با راه‌اندازی دوباره پس از به‌روزرسانی فهرست خالی می‌شود و تحویل‌های تکراری که بعد از آن می‌رسند (فرستنده‌ها معمولاً پس از خطا یا تأخیر دوباره می‌فرستند) دوباره پردازش می‌شوند. اصلاح: ثبت ماندگار شناسه‌ها در پایگاه داده یا جدول با مدت نگهداری مناسب.

  • حافظه موقت را علت می‌داند (1 امتیاز)
  • ارتباط با راه‌اندازی دوباره (1 امتیاز)
  • ثبت ماندگار (1 امتیاز)
  • فرستنده خراب است ← تحویل تکراری رفتار عادی فرستنده است؛ گیرنده باید آماده باشد.

گیرنده Webhook پس از دریافت رویداد «پیام تازه» باید پاسخ مدل زبانی را بسازد که ۲۰ ثانیه طول می‌کشد. فرستنده اگر ظرف ۱۰ ثانیه پاسخ نگیرد، دوباره می‌فرستد. بهترین ترتیب کدام است؟

  • بررسی امضا، فراخوانی مدل، ارسال پاسخ، سپس 200.
  • بررسی امضا، ثبت شناسه، 200 سریع، سپس فراخوانی مدل و ارسال پاسخ در مسیر جدا.
  • 200 فوری بدون بررسی، سپس بررسی امضا و فراخوانی مدل.
  • فراخوانی مدل، سپس بررسی امضا، سپس 200.
پاسخ نمونه و معیار ارزیابی
  • a ← پس از ۱۰ ثانیه فرستنده دوباره می‌فرستد و تحویل تکراری می‌سازی.
  • c ← پاسخ 200 پیش از بررسی امضا به فرستنده جعلی هم تأیید می‌دهد و شناسه هم ثبت نشده است؛ بررسی امضا ارزان و سریع است، پس اول انجامش بده.
  • d ← برای پیام جعلی هم هزینه مدل می‌پردازی و به آن پاسخ می‌دهی.

درگاه پرداخت با Webhook امضاشده خبر می‌دهد «پرداخت سفارش BS-1006 موفق بود» و ورک‌فلو بر اساس آن کتاب را برای ارسال آزاد می‌کند. امضا درست است. دو کار احتیاطی دیگر که پیش از آزاد کردن کتاب انجام می‌دهی چیست؟

پاسخ نمونه و معیار ارزیابی

۱) بررسی تکراری‌نبودن رویداد با شناسه ثبت‌شده تا سفارش دو بار آزاد نشود. ۲) دوباره‌خواندن وضعیت پرداخت از API درگاه (و تطبیق مبلغ با سفارش) پیش از اقدام، چون محموله ممکن است کهنه باشد یا رویدادها به ترتیب نرسند. (مورد قابل قبول دیگر: ثبت اقدام در لاگ بدون داده حساس پرداخت.)

  • بررسی تکراری (1 امتیاز)
  • دوباره‌خواندن وضعیت از API اصلی (1 امتیاز)
  • امضا درست است پس کافی است ← امضا فرستنده را تأیید می‌کند، نه تازگی و یکتایی رویداد را.

فایل‌های درس

گیرنده Webhook با بررسی امضا و جلوگیری از پردازش تکراری

webhook_receiver.py

فرستنده رویدادهای آزمایشی: درست، تکراری، دستکاری‌شده، بدون امضا

send_webhook.py

خروجی نمونه برای مسیر بدون اجرا

sample-run.txt

ابزارها و جایگزین‌ها

  • ویرایشگر متن — طراحی گیرنده

منابع

Validating webhook deliveries GitHub Docs living doc, accessed 2026-10-16

Idempotent (Glossary) MDN Web Docs (Mozilla) living doc, accessed 2026-10-16

دوره

زبان مشترک نرم‌افزارها: HTTP، JSON و API