وبهوک ووکامرس کار نمی‌کند؟ مسیر تشخیص خطا و بازیابی سفارش‌ها
سفارش در فروشگاه ثبت شده اما در انبار یا حسابداری دیده نمی‌شود؛ فعال‌کردن دوبارهٔ وبهوک به‌تنهایی مشخص نمی‌کند سفارش‌های قبلی چه شده‌اند. برای رفع مشکل باید سه مرحله را جدا بررسی کنید: ایجاد اعلان، رسیدن درخواست به مقصد و ثبت نتیجهٔ تجاری. این راهنما برای بررسی اتصال موجود است؛ اگر هنوز روش اتصال را انتخاب نکرده‌اید، از مقایسهٔ وبهوک و واکشی دوره‌ای API شروع کنید.
قبل از تغییر تنظیمات، یک سفارش نمونه انتخاب کنید
شناسهٔ سفارش، زمان و منطقهٔ زمانی، رویداد مورد انتظار و نتیجهٔ واقعی مقصد را ثبت کنید. روشن کنید اتصال با ایجاد سفارش آغاز می‌شود یا با تغییر وضعیت آن. سفارش تازه الزاماً همان سفارش پرداخت‌شده نیست؛ انتخاب رویداد باید با قرارداد اتصال هماهنگ باشد. اگر مشکل به تأیید بانک مربوط است، راهنمای تأیید پرداخت مسیر مناسب‌تری دارد.
برای هر نمونه یک مسیر کوتاه بسازید: «رویداد در فروشگاه → تلاش ارسال → دریافت مقصد → شناسهٔ ثبت در مقصد». کنار هر مرحله، شاهد و زمان بنویسید. نبودن فاکتور در حسابداری به‌تنهایی ثابت نمی‌کند وبهوک ارسال نشده؛ شاید گیرنده پیام را گرفته و در پردازش بعدی متوقف شده باشد.
وضعیت، موضوع و نشانی مقصد را کنترل کنید
طبق راهنمای توسعهٔ وبهوک ووکامرس، تنظیمات در WooCommerce → Settings → Advanced → Webhooks قرار دارند. وضعیت Active ارسال را فعال می‌کند؛ Paused و Disabled ارسال نمی‌کنند. Topic و Delivery URL را با اتصال مورد انتظار تطبیق دهید. تغییر دامنه یا مسیر سرویس مقصد را هم بررسی کنید. بازشدن نشانی در مرورگر، پذیرش درخواست واقعی وبهوک را ثابت نمی‌کند.
مستند رسمی به ارسال ping هنگام نخستین ذخیره با وضعیت فعال اشاره می‌کند. موفقیت این بررسی اولیه را با پردازش یک سفارش واقعیِ آزمایشی یکسان نگیرید. اگر تلاش ارسال دیده نمی‌شود، پیش از ساخت وبهوک دوم، رویداد انتخاب‌شده و وضعیت اجرای کارهای پس‌زمینه را بررسی کنید؛ چند اتصال هم‌پوشان می‌توانند تشخیص و کنترل تکرار را دشوار کنند.
لاگ ارسال را کنار لاگ گیرنده بخوانید
مستند مدیریت وبهوک مسیر WooCommerce → Status → Logs و منبع webhooks-delivery را برای بررسی تحویل معرفی می‌کند. زمان، نشانی مقصد و پاسخ را با لاگ همان بازه در گیرنده مقایسه کنید. این مستند غیرفعال‌شدن خودکار پس از شکست‌های متوالی را نیز توضیح می‌دهد؛ جزئیات آستانه به تنظیمات و نسخه وابسته است. تغییر آستانه، علت خطا یا سفارش‌های جامانده را اصلاح نمی‌کند.
- تلاش ارسال نداریم: وضعیت، موضوع رویداد و مسیر اجرای پس‌زمینه را بررسی کنید.
- ارسال هست، دریافت نیست: DNS، TLS، مسیر شبکه و ثبت درخواست در پراکسی مقصد را با زمان نمونه تطبیق دهید.
- درخواست رسیده اما رد شده: متن پاسخ و کنترل‌های اعتبارسنجی گیرنده را ببینید.
- پاسخ موفق داریم اما نتیجه نداریم: صف داخلی، خطای نگاشت کالا و شناسهٔ عملیات مقصد را دنبال کنید.
کد پاسخ چه چیزی را روشن می‌کند؟
این فهرست، پیشنهاد بررسی است و علت قطعی هر پاسخ را تعیین نمی‌کند. پاسخ ۴۰۱ یا ۴۰۳ می‌تواند از اعتبارسنجی گیرنده یا لایهٔ امنیتی مسیر بیاید؛ مشخص کنید کدام سرویس آن را ساخته است. در ۴۰۴، مسیر و نسخهٔ endpoint را کنترل کنید. در ۵xx، خطای سرور مقصد را با همان زمان بخوانید. در timeout، احتمال ثبت عملیات پیش از قطع پاسخ را هم در نظر بگیرید؛ ارسال مجدد بدون بررسی می‌تواند عملیات را تکرار کند.
پاسخ موفق HTTP فقط شاهد همان مرحله است. معیار تجاری شما باید روشن باشد: مثلاً «سفارش با شناسهٔ مشخص، اقلام صحیح و یک سند مقصد ثبت شده است». اگر گیرنده قبل از ذخیرهٔ پایدار پیام پاسخ موفق می‌دهد، قطع سرویس در فاصلهٔ پاسخ تا ذخیره می‌تواند پیام را از دسترس خارج کند. برای اتصال اختصاصی پیشنهاد می‌شود پذیرش پایدار و اجرای عملیات، وضعیت‌های جدا و قابل پیگیری داشته باشند.
چطور سفارش‌های زمان قطعی را بازیابی کنیم؟
فعال‌شدن دوبارهٔ اتصال را معادل جبران خودکار گذشته فرض نکنید. ابتدا شروع و پایان بازهٔ اختلال را با حاشیهٔ زمانی مشخص ثبت کنید. فهرست سفارش‌های مشمول قرارداد اتصال را از فروشگاه بگیرید و با شناسه‌های موجود در مقصد مقایسه کنید. برای خواندن داده، WooCommerce REST API مسیر رسمی دارد؛ نتایج فهرست‌ها صفحه‌بندی می‌شوند و بررسی فقط صفحهٔ اول کافی نیست.
- فهرست بررسی بسازید: شناسهٔ فروشگاه، شناسهٔ سفارش، وضعیت فعلی و شناسهٔ مقصد را کنار هم قرار دهید.
- وضعیت مبهم را جدا کنید: اگر مقصد عملیات را انجام داده ولی پاسخ قطع شده، پیش از ارسال مجدد نتیجهٔ آن را پیدا کنید.
- پیش‌نمایش جبران بگیرید: مشخص کنید کدام رکورد ایجاد، به‌روزرسانی یا برای تصمیم انسانی نگه داشته می‌شود.
- محدود اجرا کنید: ابتدا چند نمونهٔ تأییدشده و سپس دسته‌های کنترل‌شده؛ خطاها باید قابل توقف و بررسی باشند.
- دوباره تطبیق دهید: تعداد رکوردها کافی نیست؛ اقلام، مبالغ و وضعیت توافق‌شده را نیز مقایسه کنید.
این روش پیشنهادی طراحی است. اگر بین زمان اعلان و بازیابی، سفارش لغو یا بازپرداخت شده باشد، بازپخش کورکورانهٔ دادهٔ قدیمی ممکن است نتیجهٔ نادرست بسازد. سیاست شما باید تعیین کند وضعیت فعلی خوانده می‌شود یا تاریخچهٔ رویدادها با ترتیب مشخص بازسازی می‌شود. برای قواعد سند، راهنمای اتصال حسابداری را ببینید.
مثال فرضی: مقصد ثبت کرده، پاسخ نرسیده است
فرض کنید گیرنده سفارش آزمایشی را در حسابداری ثبت می‌کند، اما ارتباط پیش از برگشت پاسخ قطع می‌شود. اپراتور دوباره آن را می‌فرستد. اگر هر درخواست به معنی «ساخت سند تازه» باشد، یک خرید می‌تواند دو سند بسازد. راهکار پیشنهادی، نگهداری نگاشت پایدار میان فروشگاه، سفارش و عملیات مقصد و جلوگیری از اجرای دوبارهٔ همان عملیات است.
شناسهٔ سفارش به‌تنهایی برای حذف همهٔ پیام‌های بعدی کافی نیست؛ یک سفارش می‌تواند تغییر وضعیت و اصلاح معتبر داشته باشد. کلید کنترل تکرار باید با نوع عملیات و قرارداد نسخه یا رویداد هماهنگ شود. همچنین دو درخواست هم‌زمان نباید هر دو از بررسی «هنوز ثبت نشده» عبور کنند؛ کنترل یکتایی و ثبت عملیات باید در طراحی گیرنده لحاظ شود. این مثال نتیجهٔ پروژهٔ مشتری نیست.
شش آزمون پذیرش پس از اصلاح
- رویداد انتخاب‌شده برای یک سفارش آزمایشی، نتیجهٔ مورد انتظار در مقصد بسازد.
- ارسال دوبارهٔ همان عملیات، سند تکراری ایجاد نکند.
- قطع پاسخ پس از ثبت مقصد، به وضعیت مبهم قابل پیگیری برسد.
- تغییر معتبر بعدی سفارش به اشتباه پیام تکراری تشخیص داده نشود.
- قطعی کوتاه و بازیابی، فهرست جامانده‌ها و گزارش جبران قابل بررسی داشته باشد.
- دادهٔ ناقص یا کالای نگاشت‌نشده، خطای روشن بدهد و عملیات ناقص پنهان نسازد.
آزمون‌ها را با دادهٔ ساختگی در محیط آزمایشی اجرا کنید و نتیجهٔ مورد انتظار و مشاهده‌شده را بنویسید. هنگام کنترل امضا، منطق اعتبارسنجی را برای عبور آزمایش خاموش نکنید؛ از تنظیمات معتبر محیط آزمون استفاده کنید. لاگ عمومی نباید شامل کلید، Secret، نشانی و تلفن مشتری باشد. برای اقلام نامشخص، راهنمای نگاشت SKU و تنوع کمک می‌کند.
برای بررسی اتصال چه اطلاعاتی بفرستید؟
نام سامانهٔ مقصد، رویداد مورد انتظار، زمان اختلال، یک شناسهٔ نمونه و بخش پاک‌سازی‌شدهٔ خطا را آماده کنید. در خدمت اتوماسیون و اتصال ووکامرس، مسیر داده، محدودهٔ اصلاح و معیار پذیرش مشخص می‌شود. در فرم درخواست بررسی اتصال بنویسید مشکل «نرسیدن سفارش»، «ثبت تکراری» یا «توقف پس از دریافت» است.