参考文献 / アーカイブと連携機能

送信されるWebhook

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

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

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

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

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

ペイロードと署名#

スキーマ：tgwitness.webhook/1。すべてのペイロードには 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の例#

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

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