# Telegram · وب‌هوک‌های خروجی

Canonical page: https://phishdestroy.io/tgwitness/fa/docs/reference/webhooks/

ارسال رویدادهای محدودشده به گیرندگان HTTPS با امضاهای HMAC، تلاش‌های مجدد و وضعیت تحویل.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/fa/llms.txt)

ارسال رویدادهای محدودشده به گیرندگان HTTPS با امضاهای HMAC، تلاش‌های مجدد و وضعیت تحویل.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [مستندسازی](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [یکپارچه‌سازی‌های آرشیو](https://phishdestroy.io/tgwitness/fa/docs/reference/cli/)

![یکپارچه‌سازی‌های آرشیو](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

[راهنمای گردش کار](https://phishdestroy.io/tgwitness/docs/archive/) · [ویکی](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

در فضای کاری انتخاب‌شده، **ابزارهای بیشتر → ادغام‌ها → وب‌هوک‌های خروجی را** باز کنید. یک گیرنده HTTPS اضافه کنید، رویدادهای گردآورنده/رسانه/خروجی را انتخاب کنید و به صورت اختیاری، چت‌ها را برای مشاهدات جدید و تغییرات برگزینید. متن پیام به صورت پیش‌فرض غیرفعال است. فعال کردن گزیده‌ها حداکثر 1,000 کاراکتر به رویدادهای تغییر پیام اضافه می‌کند؛ فیلدها و اعتبارنامه‌های خام تلگرام هرگز ارسال نمی‌شوند.

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

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

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

اسکما: [`tgwitness.webhook/1`](https://github.com/phishdestroy/TgWitness/blob/main/integrations/webhook.schema.json). هر بارگذاری حاوی `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 در صف قرار می‌گیرند. آنها از معناشناسی حداقل-یک‌بار استفاده می‌کنند: یک تأیید دریافت‌شده از دست رفته یا راه‌اندازی مجدد ممکن است یک رویداد را با همان شناسه دوباره تحویل دهد. هشت تلاش با فاصله زمانی نمایی وجود دارد که از 15 ثانیه شروع شده و حداکثر تا یک ساعت ادامه دارد. موفقیت نیازمند یک پاسخ 2xx است. کاری که تمام تلاش‌های خود را مصرف می‌کند، با خطای خود برای بازبینی همچنان قابل مشاهده باقی می‌ماند.

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

## نمونه‌ی n8n

[جریان کاری نمونه را](https://github.com/phishdestroy/TgWitness/blob/main/integrations/n8n-tgwitness.json) وارد کنید. این جریان غیرفعال است و هیچ راز یا اقدام بعدی ندارد. `TGWITNESS_WEBHOOK_SECRET` را در محیط کارگر n8n تنظیم کنید، به آن محیط دسترسی بدهید و برای گره کد، افزونه داخلی `crypto` را مجاز کنید. این مثال از گزینه raw-body گره Webhook استفاده می‌کند، امضا/تازگی را بررسی می‌کند و رویدادهای تأییدشده را تأیید می‌نماید. این با [پیاده‌سازی مستندشده](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Webhook/Webhook.node.ts) این گره مطابقت دارد.

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