معرفی وب‌هوک

📖 مقدمه

به جای اینکه هر چند ثانیه بپرسید «چیزی تغییر کرد؟»، سلر ۳۶۰ هر تغییر را به محض رخ دادن به نشانی سرور شما می‌فرستد؛ مثلا تغییر موجودی، سفارش تازه یا واریز دیجی‌کالا.

⚙️ ساخت نشانی

1. یک نشانی HTTPS در سرور خود بسازید که درخواست POST با بدنه‌ی JSON بپذیرد.
2. با POST /v1/webhooks (دسترسی webhooks:manage) نشانی و رویدادهای دلخواه را ثبت کنید. کلید امضا (secret) فقط در همین پاسخ نمایش داده می‌شود.
3. با POST /v1/webhooks/{webhook_id}/test یک پیام آزمایشی ping بفرستید و نتیجه را ببینید.

• حداکثر ۵ نشانی برای هر پنل.
• نشانی نباید به آی‌پی داخلی یا خصوصی اشاره کند؛ تغییر مسیر (redirect) دنبال نمی‌شود.

✉️ شکل پیام

{
  "id": "evt_01HZY3K8",
  "type": "stock.changed",
  "created_at": "2026-11-11T17:43:22+03:30",
  "panel_id": 1,
  "livemode": true,
  "data": { }
}

همراه هر پیام، سرآیند S360-Signature می‌آید. پیش از استفاده، امضا را بررسی کنید.

✅ پاسخ شما

• ظرف ۱۰ ثانیه یک پاسخ 2xx بدهید. هر پاسخ دیگر یا نرسیدن پاسخ، شکست حساب می‌شود.
• کار سنگین را پس از پاسخ و در پس‌زمینه انجام دهید.

🔁 تلاش دوباره

تلاش	فاصله پس از تلاش قبلی
۲	۱ دقیقه
۳	۵ دقیقه
۴	۱۵ دقیقه
۵	۱ ساعت
۶	۳ ساعت
۷	۶ ساعت
۸	۱۲ ساعت

اگر نشانی ۲۴ ساعت پیاپی شکست بخورد، غیرفعال می‌شود و دلیل آن در disabled_reason می‌آید. گزارش همه‌ی تحویل‌ها با GET /v1/webhooks/{webhook_id}/deliveries در دسترس است و هر تحویل را می‌توانید دوباره بفرستید.

⚠️ تکرار و ترتیب

پیام ممکن است تکراری برسد

اگر پاسخ شما دیر برسد، همان پیام دوباره فرستاده می‌شود. id هر رویداد در همه‌ی تلاش‌ها ثابت است؛ رویدادی را که قبلا پردازش کرده‌اید، کنار بگذارید.

پیام ممکن است جابه‌جا برسد

ترتیب رسیدن پیام‌ها تضمین نمی‌شود. برای ترتیب از version (در موجودی) یا زمان خود داده استفاده کنید، نه زمان رسیدن پیام.

تور ایمنی

اگر سرور شما مدتی در دسترس نبود، با GET /v1/events?after=<آخرین شناسه> همه‌ی رویدادهای ۷ روز گذشته را به ترتیب بخوانید.

🔔 فهرست رویدادها

حوزه	رویداد	چه وقت
عمومی	job.completed	یک کار دسته‌ای تمام شد
عمومی	ping	پیام آزمایشی دکمه‌ی «ارسال وب‌هوک آزمایشی»
کالا و موجودی	product.moderation_changed	وضعیت تایید محتوای یک کالا تغییر کرد
کالا و موجودی	purchase.needed	کالایی خرید لازم دارد
کالا و موجودی	purchase_order.late	سفارش خرید دیرکرد دارد
کالا و موجودی	stock.changed	موجودی یا «قابل فروش» یک تنوع تغییر کرد
کالا و موجودی	stock.low	باقی‌مانده در انبار دیجی‌کالا پیش از رسیدن محموله‌ی تازه تمام می‌شود
کالا و موجودی	stock.out	تنوع ناموجود شد
کالا و موجودی	stock.stockout_soon	کل موجودی قابل فروش به‌زودی تمام می‌شود
کالا و موجودی	stock_split.group_needs_attention	یک گروه تقسیم موجودی بررسی شما را لازم دارد
کالا و موجودی	stock_split.run_completed	یک اجرای تقسیم موجودی تمام شد
کالا و موجودی	storage.cost_rising	هزینه‌ی انبارداری محسوس افزایش یافت
کالا و موجودی	variant.request_completed	یک درخواست ساخت تنوع تمام شد
کالا و موجودی	variant.status_changed	فعال یا غیرفعال شدن یا تغییر وضعیت تایید یک تنوع
قیمت و رقابت	bot.plan_quota_over	تعداد تنوع‌های دارای ربات از سقف اشتراک بیشتر شد
قیمت و رقابت	bot.rate_limited	دیجی‌کالا درخواست‌های ربات را موقتا محدود کرده است
قیمت و رقابت	bot.stalled	ربات روشن است اما قیمت‌ها را بررسی نمی‌کند
قیمت و رقابت	bot.variant_stopped	ربات برای یک تنوع متوقف شد
قیمت و رقابت	bot.writes_failing	قیمت‌های ربات در دیجی‌کالا ثبت نمی‌شود
قیمت و رقابت	buybox.lost	بای‌باکس یک تنوع از دست رفت
قیمت و رقابت	buybox.won	بای‌باکس یک تنوع به دست آمد
قیمت و رقابت	competitor.below_floor	رقیب با قیمتی کمتر از حداقل قیمت شما می‌فروشد
قیمت و رقابت	price.changed	قیمت فروش یک تنوع تغییر کرد
قیمت و رقابت	price.selling_at_loss	یک تنوع با قیمت فعلی زیان‌ده است
قیمت و رقابت	promotion.below_floor	تخفیف فعال یک تنوع کمتر از حداقل قیمت شماست
قیمت و رقابت	promotion.ending	تخفیف یک تنوع به‌زودی تمام می‌شود
قیمت و رقابت	promotion.rejected	دیجی‌کالا تخفیف یا پیوستن به کمپین را نپذیرفت
سفارش و ارسال	commitment.late	تعهد ارسال یک تنوع دیر شد
سفارش و ارسال	consignment_draft.built	محموله‌ی یک پیش‌نویس در دیجی‌کالا ثبت شد
سفارش و ارسال	consignment_draft.missed	مهلت یک پیش‌نویس بدون ساخت محموله تمام شد
سفارش و ارسال	order.cancelled	لغو کامل یا یک قلم سفارش
سفارش و ارسال	order.created	سفارش تازه در دیجی‌کالا
سفارش و ارسال	order.returned	برگشت واحدی از سفارش به انبار دیجی‌کالا
سفارش و ارسال	package.received_incomplete	محموله ناقص دریافت شد
سفارش و ارسال	package.status_changed	وضعیت یک محموله تغییر کرد
سفارش و ارسال	replenish.skipped	بررسی روزانه‌ی انبارش هوشمند انجام نشد
سفارش و ارسال	slot.freed	نوبتی که پر شده بود دوباره آزاد شد
سفارش و ارسال	slot.low	ظرفیت باقی‌مانده‌ی نوبت‌های یک روز تغییر کرد
سفارش و ارسال	slot.opened	نوبت تازه در انبار پایش‌شده باز شد
مالی و گزارش	payout.created	واریز تازه‌ی دیجی‌کالا
مالی و گزارش	payout.forecast_missed	مبلغ واریز با پیش‌بینی فاصله دارد
مالی و گزارش	payout.late	موعد یک واریز سپری شده است
مالی و گزارش	payout.overdue	واریز مورد انتظار ثبت نشده است
مالی و گزارش	payout.rejected	یک واریز برگشت خورد
مالی و گزارش	penalty.created	جریمه‌ی تازه
مالی و گزارش	penalty.rising	جریمه‌ها به‌طور محسوس افزایش یافته است

جزئیات هر رویداد در صفحه‌ی حوزه‌ی خودش آمده است.