وب‌هوک‌های خروجی

نسخهٔ اصلی کنونی: از نسخهٔ سورس استفاده کنید؛ پیش‌نمایش قابل‌حمل نسخهٔ ۰.۷.۰ پیش از این قابلیت عرضه شده است.

راهنمای گردش کار · ویکی

در فضای کاری انتخاب‌شده، «ادغام‌ها» → «وب‌هوک‌های خروجی» را باز کنید. یک گیرنده HTTPS اضافه کنید، رویدادهای جمع‌آوری‌کننده/رسانه/خروجی را انتخاب کنید و اختیاریاً چت‌ها را برای مشاهدات جدید و تغییرات برگزینید. متن پیام به طور پیش‌فرض غیرفعال است. فعال‌سازی گزیده‌ها حداکثر ۱۰۰۰ کاراکتر به رویدادهای تغییر پیام اضافه می‌کند؛ فیلدهای خام تلگرام و اطلاعات هویتی هرگز ارسال نمی‌شوند.

یک‌بار کلید مخفی HMAC را در پیکربندی محافظت‌شده گیرنده کپی کنید. این کلید در گاوصندوق TgWitness رمزگذاری شده و از طریق پنل قابل بازیابی نیست. برای چرخاندن کلید، یک مقصد را حذف کرده و دوباره ایجاد کنید. یک تست بدون محتوای چت را به صف‌های آزمایشی مصنوعی ارسال کنید؛ وضعیت تحویل را برای مشاهده نتیجه آن، تازه کنید.

امکان ارسال، حلقه اعلان موجود را در کنار Apprise گسترش می‌دهد. این قابلیت از مسیر خارجی فضای کاری و محدودیت‌های مقصد خصوصی موجود استفاده می‌کند. هیچ بازگشتی (fallback) یا هدایت (redirect) مستقیمی پس از آن صورت نمی‌گیرد. آدرس‌های اینترنتی نباید حاوی اطلاعات ورود به سیستم، رشته‌های پرس‌وجو (query strings) یا قطعات (fragments) باشند؛ آدرس‌های خصوصی نیازمند تأیید شبکه در سطح سرور هستند، نه تنظیمی که کاربر پنل بتواند آن را دور بزند.

بار مفید و امضا#

اسکما: tgwitness.webhook/1. هر بارگذاری حاوی event_id، timestamp، workspace، type، synthetic و شمارنده‌ها است. رویدادهای مبتنی بر ژورنال، توالی و هش خود را شامل می‌شوند. تکمیل خروجی‌گیری کامل و تست‌های مصنوعی، رویدادهای تحویل هستند و هیچ مرجع ژورنال امضا شده ساختگی ندارند. اعلان‌های حذف تلگرام و missing_on_recheck همچنان انواع متمایزی باقی می‌مانند.

سربرگ X-TgWitness-Signature، t=UNIX_SECONDS,v1=HEX_HMAC_SHA256 است. HMAC را بر روی بایت‌های دقیق timestamp + "." + raw_request_body محاسبه کنید، با استفاده از کلید مخفی نمایش‌داده‌شده به صورت بایت‌های UTF-8. امضاها را در زمان ثابت قبل از پردازش یا اقدام روی بدنه مقایسه کنید. مهرهای زمانی را که بیش از پنج دقیقه با ساعت شما اختلاف دارند، رد کنید. مهر زمانی در هر تلاش برای تحویل، تازه می‌شود.

از event_id به عنوان یک کلید ایدمپوتنسی در ذخیره‌سازی پایدار، با یک قید یکتایی اتمی قبل از اثرات جانبی استفاده کنید. یک امضای معتبر به تنهایی از تکرار یک درخواست اخیر جلوگیری نمی‌کند. شناسه‌های پردازش‌شده را حداقل برای تمام دورهٔ پنجرهٔ تلاش مجدد نگه دارید؛ در صورتی که گیرنده بتواند رویدادهای ذخیره‌شده را مجدداً پردازش کند، آنها را برای مدت طولانی‌تری حفظ کنید.

تکرار تلاش‌ها#

ارسال‌ها به‌طور پایدار قبل از درخواست‌های HTTP در صف قرار می‌گیرند. آن‌ها از معناشناسی «حداقل یک‌بار» استفاده می‌کنند: یک تأیید از دست رفته یا راه‌اندازی مجدد ممکن است یک رویداد را با همان شناسه دوباره ارسال کند. هشت تلاش با فاصله زمانی نمایی وجود دارد که از ۱۵ ثانیه شروع شده و حداکثر یک ساعت است. موفقیت نیازمند پاسخ 2xx است. وظایف ناموفق یک خطای قابل مشاهده به جا می‌گذارند؛ تحویل پس از پایان تلاش‌های مجدد تضمین نمی‌شود.

صف قادر به نگهداری ۱۰۰۰ تحویل است. هنگامی که پر شود، اسکن رویدادهای دفترچه وقایع متوقف شده و پس از آزاد شدن فضا از سر گرفته می‌شود. تکمیل یک خروجی‌گیری کامل که قابل صف‌بندی نیست، یک خطای صف قابل مشاهده را ایجاد می‌کند. در هر گذر اطلاع‌رسانی، حداکثر پنج تحویل تلاش می‌شود و ۱۰۰ رکورد اخیر تلاش‌ها نگهداری می‌شوند. حذف یک مقصد، تحویل‌های در انتظار آن را نیز حذف می‌کند.

نمونه‌ی n8n#

جریان کاری نمونه را وارد کنید. این جریان غیرفعال است و هیچ راز یا اقدام بعدی ندارد. TGWITNESS_WEBHOOK_SECRET را در محیط کارگر n8n تنظیم کنید، به آن محیط دسترسی بدهید و برای گره کد، افزونه داخلی crypto را مجاز کنید. این مثال از گزینه raw-body گره Webhook استفاده می‌کند، امضا/تازگی را بررسی می‌کند و رویدادهای تأییدشده را تأیید می‌نماید. این با پیاده‌سازی مستندشده این گره مطابقت دارد.

پیش از افزودن خروجی‌های SIEM یا اعلان‌ها، یک ذخیره‌سازی پایدار و ایزوپوتنت با کلیدگذاری بر پایevent_id اضافه کنید. ویرایش گردش کار n8n و نگهداری گزارش اجرای آن را بر اساس داده‌هایی که برای ارسال انتخاب کرده‌اید، محدود کنید. TgWitness هیچ فرمان ورودی‌ای اضافه نمی‌کند.