وب‌هوک‌ها و رویدادها

پنل هر بار که چیزی ارزش دانستن داشته باشد یک رویداد ایجاد می‌کند: مشتری که ترافیکش رو به اتمام است، نودی که از کار افتاده، ورودی از یک آدرس تازه، پشتیبانی که شکست خورده. مشترک وب‌هوک آدرسی از شماست که رویدادهایی را که خواسته، به شکل درخواست‌های HTTPS امضاشده، دریافت می‌کند. این صفحه درباره‌ی افزودن مشترک‌ها، بررسی آنچه به آن‌ها رسیده و تنظیم آستانه‌های هشدار است. زیر سرویس‌ها ← وب‌هوک‌ها است.

چت‌های تلگرام و آدرس‌های ایمیل همین رویدادها را از صفحه‌های خودشان می‌گیرند: ببینید تلگرام و ایمیل. همه‌ی رویدادها و فیلدهایشان در فهرست رویدادها فهرست شده‌اند؛ اینکه گذرگاه رویدادها در درون چطور کار می‌کند در گذرگاه رویداد آمده است.

افزودن مشترک

1. افزودن.
2. نام: گیرنده چیست.
3. آدرس: جایی که پنل هر رویداد را با POST به آن می‌فرستد.
4. رویدادها: برای دریافت همه‌ی رویدادها، از جمله رویدادهایی که نسخه‌های بعدی اضافه می‌کنند، همهٔ رویدادها را بگذارید، یا تیکش را بردارید و انتخاب کنید.
5. فقط رویدادهای مربوط به: همه را بگذارید، یا یک حساب را انتخاب کنید تا فقط رویدادهای مربوط به آن را بگیرد: کاربران یک نماینده، ورودهای خودش.
6. متعلق به: بدون افزونه (وبهوک دستی) را بگذارید، مگر اینکه گیرنده افزونه‌ی خودتان باشد که کنار پنل اجرا می‌شود (پایین‌تر).
7. ذخیره.

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

ارسال رویداد آزمایشی روی ردیف، همان لحظه یک panel.ping به آن مشترک می‌فرستد و پاسخ گیرنده را نشان می‌دهد.

کدام آدرس‌ها مجازند

آدرسی که اینجا تایپ می‌شود نمی‌تواند به هاست خود پنل یا شبکه‌ی خصوصی‌اش اشاره کند: loopback، بازه‌های خصوصی، link-local و آدرس‌های مشابه هنگام اتصال پنل رد می‌شوند. این کار نمی‌گذارد از وب‌هوک برای رسیدن به سرویس‌هایی استفاده شود که قرار است درونی بمانند.

وب‌هوکی که متعلق به توکن یک افزونه است (متعلق به) می‌تواند به همین هاست و شبکه‌ی خصوصی‌اش، مثل یک شبکه‌ی Docker، برسد، چون افزونه‌ای که کنار پنل است همانجا اجرا می‌شود. آدرس‌های link-local و metadata برای آن هم رد می‌شوند. متعلق به بعداً قابل تغییر نیست. افزونه‌ی امضاشده وب‌هوک خودش را ثبت می‌کند؛ ببینید صفحه‌ی افزونه‌ها.

یک ارسال چه شکلی دارد

هر رویداد یک POST با بدنه‌ی JSON است:

{
  "v": 1,
  "id": 4182,
  "event": "node.disconnected",
  "time": 1760180000,
  "data": { "nodeId": 3, "name": "de-1", "status": "error", "message": "connection refused" }
}

با این هدرها:

هدر	چه دارد
X-Nexora-Event	نام رویداد، همان که در بدنه است
X-Nexora-Delivery	شناسه‌ی این ارسال؛ در هر تلاش دوباره همان است
X-Nexora-Signature	t=<unix seconds>,v1=<hex>

مقدار v1 برابر HMAC-SHA256(secret, "<t>.<body>") است: مُهر زمانی، یک نقطه، و سپس بدنه‌ی خام دقیقاً همان‌طور که دریافت شده. گیرنده همین مقدار را با کلیدش حساب می‌کند، دو مقدار را در زمان ثابت مقایسه می‌کند، و درخواستی را که t آن بیش از پنج دقیقه با ساعت خودش فاصله دارد رد می‌کند. ساختار کامل و یک نمونه‌ی حل‌شده در فهرست رویدادها آمده است.

پاسخ 2xx یعنی ارسال انجام شد. هر چیز دیگری، از جمله redirect، یا بی‌پاسخ ماندن تا ده ثانیه، شکست است. redirectها دنبال نمی‌شوند.

محتوای رویدادها کم‌حجم است: شناسه‌ها، نام‌ها و عددها، هرگز گذرواژه، کلید یا لینک اشتراک. گیرنده‌ای که بیشتر لازم دارد آن را با یک توکن از API می‌خواند (ببینید توکن‌های API).

تلاش‌های دوباره و رشته‌ی شکست‌ها

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

ارسال‌ها به یک مشترک یکی‌یکی و به ترتیب انجام می‌شوند، پس گیرنده user.disabled را پیش از user.enabled بعدی‌اش می‌بیند.

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

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

سابقه‌ی ارسال‌ها

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

ارسال دوباره روی هر ارسال آن را یک بار دیگر، با شمارش تازه‌ی تلاش‌ها، در صف می‌گذارد. شناسه‌ی X-Nexora-Delivery خودش را نگه می‌دارد، پس گیرنده‌ای که شناسه‌های دیده‌شده را نادیده می‌گیرد این را هم نادیده می‌گیرد.

سابقه به‌طور پیش‌فرض هفت روز نگه داشته می‌شود. تنظیم event_retention_days (تا ۹۰) آن را تغییر می‌دهد، با nexora-panel config set (ببینید خط فرمان).

تعویض کلید

تعویض کلید روی یک ردیف کلید امضای تازه‌ای می‌سازد و یک بار نشانش می‌دهد. اول گیرنده را به‌روز کنید: کلید قبلی از ارسال بعدی دیگر کار نمی‌کند.

مشترکی که برچسب بدون امضا دارد از تک‌آدرس وب‌هوک پنل‌های قدیمی‌تر آمده و کلیدی ندارد، پس ارسال‌هایش امضا ندارند. یک کلید برایش بسازید و به گیرنده بدهید.

هشدارهای میزبان

کارت هشدارهای میزبان تعیین می‌کند پنل کی هشدارهای نود را ایجاد کند:

فیلد	پیش‌فرض	چه ایجاد می‌کند
مصرف دیسک	۹۰٪	node.disk_high وقتی فایل‌سیستم ریشه‌ی یک نود از آن بگذرد، node.disk_recovered وقتی پنج واحد پایین‌تر برگردد
مصرف حافظه	۹۰٪	node.memory_high و node.memory_recovered، به همان شکل
اتصال‌های ردشده در ساعت	۱۰۰	node.rejections_high وقتی یک نود در یک ساعت لغزان بیش از این تعداد اتصال را از راه یک اوتباند مسدودکننده رد کند

دیسک و حافظه هر پنج دقیقه از هر نود متصل خوانده می‌شوند. شمارش اتصال‌های ردشده در هر heartbeat از خود نود می‌آید: اتصال‌هایی را می‌شمارد که از راه یک اوتباند مسدودکننده رد شده‌اند، مثل block-torrent در پیش‌تنظیم تورنت (ببینید مسیریابی و DNS). هر هشدار برای هر بار گذشتن از آستانه یک بار ایجاد می‌شود، هرگز برای هر خواندن یا هر اتصال. 0 آن هشدار را خاموش می‌کند.

هشدارهای حساب

کارت هشدارهای حساب دو هشدار را درباره‌ی حساب‌هایی تنظیم می‌کند که هنوز کار می‌کنند:

فیلد	پیش‌فرض	چه ایجاد می‌کند
مصرف ترافیک	۸۰٪	user.quota_warning وقتی حسابی از این سهم ترافیکش بگذرد
روز مانده به انقضا	7,1	user.expiring وقتی حسابی پیش از تاریخش وارد یکی از این بازه‌ها شود

چند روز را با کاما جدا کنید؛ فوری‌ترین بازه‌ای که از آن گذشته فرستاده می‌شود. هر هشدار یک بار گفته می‌شود و دوباره آماده می‌شود: تمدید، ترافیک بیشتر یا بازنشانی مصرف شمارش را از نو شروع می‌کند. 0 آن هشدار را خاموش می‌کند.

وب‌هوک‌های افزونه‌ها

وب‌هوکی که در اختیار یک افزونه است با برچسب افزونه: name نشان داده می‌شود. اینجا قابل ویرایش یا حذف نیست؛ آن را همراه افزونه در صفحه‌ی صفحه‌ی افزونه‌ها مدیریت کنید. اگر رشته‌ی شکست‌ها خاموشش کرده باشد، کلیدش را همچنان می‌توانید اینجا دوباره روشن کنید.

مرتبط

• فهرست رویدادها: همه‌ی رویدادها، فیلدهایشان و اینکه چه کسی می‌تواند بخواندشان.
• گذرگاه رویداد: گذرگاه رویدادها چطور کار می‌کند.
• تلگرام و ایمیل: همین رویدادها برای آدم‌ها.
• توکن‌های API: خواندن بیش از آنچه یک رویداد دارد.