# 送信されるWebhook

Canonical page: https://phishdestroy.github.io/TgWitness/ja/docs/reference/webhooks/

HMAC署名、再送信、配信ステータスを付加して、指定されたイベントをHTTPS受信先に送信します。

**現在のメインバージョン：**ソースコードをチェックアウトして使用してください。0.7.0のポータブルプレビュー版には、この機能が実装されていません。

[ワークフローガイド](https://phishdestroy.github.io/TgWitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

選択したワークスペースで**連携 → 送信Webhook**を開きます。HTTPSの送信先を追加し、コレクター・メディア・エクスポートのイベントを選びます。新しい観測や変更の対象となるチャットも指定できます。メッセージ本文は既定では送信されません。抜粋を有効にすると、メッセージ変更イベントに最大1,000文字が追加されます。Telegramの生データや認証情報は送信されません。

HMACシークレットを一度だけ、受信側の保護された設定にコピーしてください。これは TgWitnessの保管庫で暗号化されており、パネルからは取得できません。宛先を削除 して再作成することで、シークレットをローテーションしてください。**合成**テストキューに、 チャットコンテンツを含まないテストメッセージ**を送信し**、配信ステータスを更新して結果を確認してください。

配信機能は、Appriseと並行して既存の通知ループを拡張します。この機能は、 ワークスペースの外部ルートと既存のプライベート宛先制限を利用します。 その後の直接的なフォールバックやリダイレクトは行われません。URLには認証情報、 クエリ文字列、フラグメントを含めてはなりません。プライベートアドレスには、 パネルユーザーがバイパスできないサーバーレベルのネットワーク オプトインが必要です。

## ペイロードと署名

スキーマ：[`tgwitness.webhook/1`](https://github.com/phishdestroy/TgWitness/blob/main/integrations/webhook.schema.json)。すべてのペイロードには `event_id`、`timestamp`、`workspace`、`type`、`synthetic`、およびカウンターが含まれます。 ジャーナルベースのイベントには、そのシーケンスとハッシュが含まれます。完全エクスポートの完了および 合成テストは配信イベントであり、架空の署名付きジャーナル参照は含まれません。 Telegramの削除通知と`missing_on_recheck`は、引き続き別個のタイプとして扱われます。

`X-TgWitness-Signature`ヘッダーは`t=UNIX_SECONDS,v1=HEX_HMAC_SHA256`です。 表示された秘密鍵をUTF-8バイトとして使用し、 `timestamp + "." + raw_request_body`の正確なバイト列に対してHMACを計算します。本文の解析や処理を行う前に、 定数時間で署名を照合してください。自身の時計から5分以上ずれている タイムスタンプは拒否してください。タイムスタンプは配信の試行ごとに更新されます。

`event_id`を、副作用が発生する前のアトミックかつ一意な 制約を伴う、耐久性のあるストレージ内の冪等性キーとして使用してください。有効な署名だけでは、 直近のリクエストがリプレイされるのを防ぐことはできません。処理済みのIDは、少なくとも リトライウィンドウ全体にわたって保持してください。受信者が保存されたイベントを再処理できる場合は、より長期間保持してください。

## 再試行

配信は、HTTPリクエストの前に永続的にキューに格納されます。これらは「少なくとも1回」 のセマンティクスを採用しています。つまり、確認応答の喪失や再起動により、 同じIDを持つイベントが再度配信される場合があります。指数関数的なバックオフを伴う8回の試行が行われ、15 秒から開始し、上限は1時間です。成功には2xxレスポンスが必要です。 処理が完了したジョブは 目に見えるエラーを残します。再試行終了後の配信は保証されません。

キューには1,000件の配信が保持されます。キューが満杯になると、ジャーナルイベントのスキャンは一時停止し、 空き容量が確保された後に再開されます。 キューに追加できない完全エクスポートの完了処理は、 目に見えるキューエラーを発生させます。通知の処理ごとに最大5回の配信が試行され、 最新の100件の試行記録が保持されます。送信先を削除すると、 その送信先の保留中の配信も削除されます。

## n8nの例

[サンプルワークフローを](https://github.com/phishdestroy/TgWitness/blob/main/integrations/n8n-tgwitness.json)インポートしてください。このワークフローは非アクティブ状態で、 機密情報や下流アクションは含まれていません。 n8nワーカー環境で`TGWITNESS_WEBHOOK_SECRET`を設定し、 その環境へのアクセスを許可するとともに、Codeノードに対して`crypto` 組み込み関数の使用を許可してください。この例では、Webhookノードのraw-bodyオプションを使用し、 署名と鮮度を確認し、検証済みのイベントに対して確認応答を行います。これは、 [ノードのドキュメントに記載されている実装と一致しています](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Webhook/Webhook.node.ts)。

SIEMへの書き込みや通知を追加する前に、`event_id`をキーとする 耐久性のある冪等性ストレージを追加してください。n8nワークフローの編集および実行ログの保持期間は、 送信対象として選択したデータに応じて制限してください。TgWitnessは受信コマンドを追加しません。