خلاصه در یک نگاه: وب هوک (Webhook) یعنی یک سرویس، هر وقت اتفاقی در آن افتاد، خودش یک درخواست HTTP به آدرسی که شما دادهاید بفرستد. مثلاً «سفارش تازه ثبت شد» یا «کاربر به ربات پیام داد». با API شما مدام میپرسید «خبر تازهای هست؟». با وب هوک، خبر خودش به سراغتان میآید.
- ووکامرس، ربات تلگرام و بازوی بله وب هوک دارند. همه داده را با درخواست POST و در قالب JSON میفرستند.
- چهار چیز وب هوک را قابل اعتماد میکند: آدرس HTTPS، بررسی امضا یا توکن مخفی، جلوگیری از پردازش تکراری و جواب سریع 200.
- درگاههای پرداخت ایرانی معمولاً وب هوک ندارند و با آدرس بازگشت (callback) و تأیید (verify) کار میکنند. اینها را با هم قاطی نکنید.
بهروزرسانی: ۱۰ آبان ۱۴۰۵. رفتار وب هوک در ووکامرس از مستندات رسمی WooCommerce، در تلگرام از مستندات Bot API و در بله از مستندات رسمی بازوی بله بازبینی شده است.
صاحب یک فروشگاه اینترنتی میخواست هر سفارش تازه سایت، بیمعطلی در گروه انبار پیام شود. برنامهنویس قبلی یک اسکریپت نوشته بود که هر پنج دقیقه از سایت میپرسید «سفارش جدید داری؟». نتیجهاش این بود که بعضی سفارشها پنج دقیقه دیر میرسیدند، بعضی دو بار میرسیدند و سرور بیشتر وقتش را صرف جواب «نه، خبری نیست» میکرد. راه درست از اول یک وب هوک بود.
در این مطلب، بدون اصطلاحات اضافی، توضیح میدهیم وب هوک چیست، چه فرقی با API دارد، در ووکامرس، تلگرام و بله چطور کار میکند و چه چیزهایی باید رعایت شود تا سفارش یا پیامی گم یا تکراری نشود. اگر تازه با مفهوم اتصال سرویسها آشنا میشوید، یکپارچهسازی API نقطه شروع خوبی است.

وب هوک چیست؟
وب هوک یک آدرس اینترنتی در سیستم شماست که سرویس دیگری قرار است هر وقت رویداد مشخصی رخ داد، اطلاعات آن رویداد را به آن بفرستد. شما فقط یک بار آدرس را ثبت میکنید و میگویید کدام رویدادها را میخواهید. از آن به بعد، سرویس مبدأ هر بار یک درخواست HTTP (تقریباً همیشه POST) با داده JSON به آن آدرس میفرستد.
یک مثال روزمره: بهجای اینکه هر ساعت به پستخانه زنگ بزنید و بپرسید بستهتان رسیده یا نه، شمارهتان را میدهید تا وقتی رسید، خودشان پیامک بزنند. API همان زنگ زدن شماست و وب هوک همان پیامک.
فرق وب هوک و API چیست؟
هر دو روی HTTP کار میکنند. فرقشان این است که چه کسی شروعکننده است. در API، سیستم شما درخواست میدهد و جواب میگیرد. در وب هوک، سرویس دیگر درخواست را میفرستد و سیستم شما جواب میدهد. در بیشتر پروژهها از هر دو با هم استفاده میشود: وب هوک خبر میدهد که چیزی عوض شده و API برای گرفتن جزئیات کامل یا انجام کار بعدی به کار میرود.
| موضوع | API (پرسیدن) | وب هوک (خبر دادن) |
|---|---|---|
| چه کسی شروع میکند | سیستم شما | سرویس مبدأ |
| سرعت رسیدن خبر | به فاصله پرسیدن بستگی دارد (مثلاً هر ۵ دقیقه) | چند ثانیه بعد از رویداد |
| بار روی سرور | درخواستهای زیاد، حتی وقتی خبری نیست | فقط وقتی رویدادی هست |
| نیاز سمت شما | فقط امکان فرستادن درخواست | یک آدرس عمومی HTTPS که همیشه در دسترس باشد |
| اگر سیستم شما خاموش باشد | بعداً دوباره میپرسید | به تلاش دوباره سرویس مبدأ بستگی دارد |
| کاربرد معمول | گرفتن فهرست، جستوجو، ثبت سفارش | سفارش جدید، پیام جدید، تغییر وضعیت |
ردیف آخر جدول مهمترین نکته است. وب هوک جای API را نمیگیرد. اگر سرور شما چند ساعت از دسترس خارج شود، بعضی خبرها ممکن است دیگر نرسند. برای همین در سیستمهای جدی، کنار وب هوک یک بررسی دورهای با API هم میگذاریم تا چیزی جا نماند.
وب هوک ووکامرس چطور کار میکند؟
در ووکامرس از مسیر «ووکامرس › پیکربندی › پیشرفته › وبهوکها» (WooCommerce › Settings › Advanced › Webhooks) یک وب هوک تازه میسازید. موضوع (Topic) را انتخاب میکنید، مثل ایجاد یا بهروزرسانی سفارش، محصول، کوپن یا مشتری. بعد آدرس مقصد (Delivery URL) را وارد میکنید و یک کلید مخفی (Secret) میگذارید. طبق مستندات ووکامرس، چند نکته را باید بدانید:
- اولین باری که وب هوک را با وضعیت فعال ذخیره کنید، ووکامرس یک درخواست آزمایشی (ping) به آدرس میفرستد.
- از روی کلید مخفی، یک هش از محتوای هر درخواست ساخته و در هدر فرستاده میشود. سیستم شما با همین هش میفهمد درخواست واقعاً از فروشگاه خودتان آمده است.
- اگر بیش از ۵ بار پشت سر هم پاسخی غیر از 2xx، 301 یا 302 بگیرد، وب هوک را خودکار غیرفعال میکند.
- گزارش ارسالها در «ووکامرس › وضعیت › گزارشها» با منبع webhooks-delivery ثبت میشود و برای پیدا کردن خطا بسیار به کار میآید.
نکته سوم در عمل زیاد دردسر میسازد. سرور مقصد چند ساعت خطا میدهد، وب هوک خاموش میشود و تا مدتها کسی متوجه نمیشود که سفارشها دیگر به انبار یا حسابداری نمیرسند. یک هشدار ساده برای «وب هوک غیرفعال شد» جلوی این را میگیرد.
وب هوک ربات تلگرام و بازوی بله
ربات تلگرام و بازوی بله دو راه برای گرفتن پیام دارند: پرسیدن دورهای با getUpdates یا ثبت وب هوک با setWebhook. این دو با هم کار نمیکنند؛ وقتی وب هوک فعال است، getUpdates جواب نمیدهد. هر پیام یا رویداد، بهصورت یک درخواست HTTPS POST با JSON به آدرس شما فرستاده میشود.
| موضوع | تلگرام (Bot API) | بله (بازو) |
|---|---|---|
| متد ثبت | setWebhook | setWebhook |
| پورتهای مجاز | 443، 80، 88، 8443 | 443، 88 |
| تأیید فرستنده | پارامتر secret_token و هدر X-Telegram-Bot-Api-Secret-Token | در مستندات عمومی پارامتری برای توکن مخفی ندیدیم؛ آدرس را غیرقابل حدس بسازید |
| تلاش دوباره | اگر پاسخ 2xx نباشد، چند بار دوباره میفرستد | در مستندات جزئیاتی نیامده است |
| شناسه یکتا برای جلوگیری از تکرار | update_id | update_id |
تلگرام طبق مستنداتش رویدادهای تحویلنشده را حداکثر ۲۴ ساعت نگه میدارد. پس اگر سرور ربات بیشتر از یک روز خاموش بماند، پیامهای آن بازه از دست میروند. برای کسبوکاری که از ربات سفارش میگیرد، این یعنی پایش سرور ربات یک کار جانبی نیست، بخشی از خود فروش است. ساخت ربات فروش را در ربات بله برای کسبوکار و ربات ایتا برای کسبوکار مفصل توضیح دادهایم.

درگاه پرداخت وب هوک است؟
معمولاً نه، و این اشتباه رایجی است. بیشتر درگاههای پرداخت ایرانی بعد از پرداخت، خود خریدار را با مرورگرش به آدرس بازگشت (callback) سایت شما برمیگردانند. سایت باید همان لحظه با درخواست تأیید (verify) از درگاه بپرسد که پرداخت واقعاً موفق بوده یا نه. اگر خریدار قبل از برگشتن صفحه را ببندد یا اینترنتش قطع شود، این مرحله ممکن است انجام نشود. پول کم شده، ولی سفارش «پرداختنشده» میماند.
چون این بازگشت به مرورگر خریدار وابسته است، نمیشود مثل وب هوک به آن تکیه کرد. راهش یک بررسی دورهای است که سفارشهای نیمهکاره را با درگاه چک کند و برای واریزهای تأییدنشده هم روال پیگیری داشته باشد. دلیلها و راهحلها را در پرداخت ناموفق در فروشگاه اینترنتی و تطبیق واریزها با بانک را در مغایرت گیری بانکی خودکار آوردهایم.
اگر میخواهید سفارشهای سایت، پیامهای ربات یا فرمهای تماس بدون معطلی به انبار، CRM یا حسابداری برسد، از فرم تماس پیام بگذارید یا با ۰۹۹۱۵۶۱۵۹۴۶ تماس بگیرید. سطحهای همکاری را در صفحه قیمتها ببینید.
چطور یک وب هوک قابل اعتماد بسازیم؟
ثبت آدرس پنج دقیقه کار دارد. کار اصلی سمت گیرنده است: آدرسی که همیشه در دسترس باشد، درخواست جعلی را رد کند، یک رویداد را دو بار پردازش نکند و با کندی سیستمهای دیگر از کار نیفتد. این قدمها را تقریباً در همه پروژههای ما میبینید:
- آدرس HTTPS با گواهی معتبر. تلگرام و بله فقط HTTPS میپذیرند و ووکامرس هم بهتر است فقط به HTTPS بفرستد.
- بررسی فرستنده. در ووکامرس هش ساختهشده از کلید مخفی را بررسی کنید و در تلگرام هدر توکن مخفی را. اگر این بررسی را نگذارید، هر کسی میتواند درخواست جعلی بفرستد.
- جواب سریع، کار بعداً. درخواست را ذخیره کنید، فوراً 200 برگردانید و کار سنگین (ساخت فاکتور، پیامک، ارسال به حسابداری) را در یک صف انجام دهید. اگر جواب دیر برسد، سرویس مبدأ خیال میکند ارسال شکست خورده و دوباره میفرستد.
- جلوگیری از تکرار. شناسه هر رویداد (مثلاً update_id یا شناسه سفارش همراه با نوع رویداد) را ذخیره کنید و رویداد تکراری را نادیده بگیرید. تلاش دوباره یعنی تکرار حتماً پیش میآید.
- ثبت همه درخواستها. متن خام هر درخواست و نتیجه پردازشش را چند هفته نگه دارید. بیشتر خطاها با همین گزارش پیدا میشوند.
- بررسی دورهای. روزی یکی دو بار با API چک کنید که چیزی جا نمانده باشد، مثلاً سفارشهایی که در سایت هستند ولی در انبار نه.
- هشدار. اگر وب هوک غیرفعال شد یا چند ساعت هیچ رویدادی نرسید، به یک نفر پیام برسد.
یک مثال: سفارش ووکامرس تا گروه انبار و حسابداری
مثال فرضی: فروشگاهی روی ووکامرس که میخواهد هر سفارش پرداختشده هم در گروه انبار پیام شود و هم پیشنویس فاکتور در نرمافزار حسابداری ساخته شود.
- یک وب هوک ووکامرس برای «بهروزرسانی سفارش» با کلید مخفی ساخته میشود.
- سرویس گیرنده امضا را بررسی میکند، درخواست را ذخیره میکند و در کسری از ثانیه 200 برمیگرداند.
- در صف، فقط سفارشهایی که وضعیتشان «در حال انجام» شده پردازش میشوند. اگر این سفارش قبلاً پردازش شده باشد، کنار گذاشته میشود.
- پیام خلاصه سفارش با بازوی بله یا ربات تلگرام به گروه انبار فرستاده میشود.
- پیشنویس فاکتور با API نرمافزار حسابداری ساخته میشود. اگر حسابداری در دسترس نبود، کار در صف میماند و بعداً دوباره امتحان میشود.
- هر شب یک بررسی با API ووکامرس، سفارشهای پرداختشده روز را با فاکتورهای ساختهشده مقایسه میکند.
فرق این طراحی با همان اسکریپت پنجدقیقهای اول مطلب، همین قدمهای ۲، ۳ و ۶ است: نه سفارشی دیر میرسد، نه دو بار ثبت میشود، نه بیصدا گم میشود. اتصال کامل سایت به حسابداری را در اتصال سایت به نرمافزار حسابداری و رساندن فرمهای سایت به CRM را در اتصال فرم سایت به CRM توضیح دادهایم.

هزینه راهاندازی وب هوک چقدر است؟
خود وب هوک هزینهای ندارد؛ ووکامرس، تلگرام و بله برای ارسال پول نمیگیرند. هزینه به سرویس گیرندهای برمیگردد که باید ساخته و نگهداری شود. عددهای زیر برآورد پونوکد برای آبان ۱۴۰۵ است و قیمت ثابت بازار نیست.
| نوع کار | برآورد پونوکد |
|---|---|
| یک وب هوک ساده (مثلاً سفارش ووکامرس به پیام گروه)، با بررسی امضا و گزارش | حدود ۸ تا ۱۵ میلیون تومان |
| چند رویداد و چند مقصد (انبار، حسابداری، CRM) با صف، جلوگیری از تکرار و بررسی شبانه | حدود ۲۵ تا ۶۰ میلیون تومان |
| نگهداری سرور گیرنده، پایش و هشدار | ماهانه، بسته به حجم و سرور |
اگر سرویس شما روی هاست اشتراکی ارزان است، اول مطمئن شوید آدرس وب هوک همیشه در دسترس است و فایروال یا کش، درخواستهای POST را مسدود یا قدیمی نمیکند. بیشتر خرابیهایی که دیدهایم از همینجا شروع شدهاند.
چکلیست راهاندازی وب هوک
- دقیقاً میدانید کدام رویدادها لازماند و بقیه را فعال نکردهاید.
- آدرس گیرنده HTTPS با گواهی معتبر است و از اینترنت در دسترس است.
- کلید یا توکن مخفی تعریف شده و هر درخواست بررسی میشود.
- گیرنده سریع 200 برمیگرداند و کار سنگین را در صف انجام میدهد.
- شناسه رویدادها ذخیره و تکراریها نادیده گرفته میشوند.
- متن خام درخواستها و نتیجه پردازش ثبت میشود.
- یک بررسی دورهای با API دادههای جامانده را پیدا میکند.
- برای غیرفعال شدن وب هوک یا قطع رویدادها هشدار گذاشتهاید.
- یک بار در محیط آزمایشی، قطع و وصل سرور گیرنده و ارسال تکراری را امتحان کردهاید.
سؤالهای رایج
وب هوک به زبان ساده یعنی چه؟
یعنی یک سرویس، هر وقت اتفاقی در آن افتاد، خودش با یک درخواست HTTP به سیستم شما خبر بدهد. لازم نیست سیستم شما مرتب بپرسد خبری هست یا نه.
وب هوک امن است؟
اگر درست ساخته شود، بله: آدرس HTTPS باشد و هر درخواست با امضا یا توکن مخفی بررسی شود. وب هوکی که فرستنده را بررسی نمیکند، درخواست جعلی را هم میپذیرد.
وب هوک ووکامرس چرا خودکار غیرفعال میشود؟
طبق مستندات ووکامرس، اگر بیش از ۵ ارسال پشت سر هم پاسخی غیر از 2xx، 301 یا 302 بگیرد، وب هوک غیرفعال میشود. علت را در گزارش webhooks-delivery پیدا کنید و بعد از رفع مشکل، دوباره فعالش کنید.
برای ربات تلگرام وب هوک بهتر است یا getUpdates؟
برای رباتهای واقعی که سرور همیشه روشن دارند، وب هوک سریعتر است و بار کمتری دارد. getUpdates برای آزمایش یا وقتی آدرس عمومی HTTPS ندارید سادهتر است. این دو همزمان کار نمیکنند.
بازوی بله از وب هوک پشتیبانی میکند؟
بله. طبق مستندات رسمی بله، با متد setWebhook یک آدرس HTTPS ثبت میکنید و رویدادها روی پورت 443 یا 88 با درخواست POST و JSON فرستاده میشوند.
فرق وب هوک با callback درگاه پرداخت چیست؟
وب هوک را سرور سرویس مبدأ مستقیم به سرور شما میفرستد. callback درگاه، خود خریدار را با مرورگرش به سایت برمیگرداند و اگر خریدار صفحه را ببندد، ممکن است اصلاً انجام نشود.
مطالب مرتبط
- یکپارچهسازی API ۱۴۰۵
- ربات بله برای کسبوکار
- پرداخت ناموفق در فروشگاه اینترنتی
- اتصال سایت به نرمافزار حسابداری
اتصال سیستمها با وب هوک در پونوکد
ما در پونوکد (Ponocode) قبل از نوشتن کد، فهرست رویدادها و مقصدها را با شما مشخص میکنیم. بعد گیرندهای میسازیم که امضا را بررسی کند، تکراریها را کنار بگذارد، کار را در صف انجام دهد و اگر چیزی قطع شد، خبر بدهد. خدمات و طراحی سایت و پنل ما را ببینید و برای برآورد اولیه به صفحه قیمتها سر بزنید.
برای مشاوره: تلفن ۰۹۹۱۵۶۱۵۹۴۶، تلگرام https://t.me/resonea، یا از فرم تماس پیام بگذارید.



