このページは英語のページを機械翻訳したものです。内容は英語のページが正です。 英語のページを読む
サーバーの Webhook
Webhook は、通報、登録の申請、アカウントの作成とプロフィールの変更、モデレーションの措置、異議申し立て、ドメインへの措置、ローカルの公開投稿、カスタム絵文字の管理操作を、Slack や Discord への中継、チケット管理システム、n8n のような自動化ツールに送ります。Webhook を設定していないサーバーは、余分な行を保存せず、余分なジョブも実行しません。受け取り側に届くもの(ヘッダー、署名、イベント、本文)は Webhook リファレンスで説明しています。
Webhook を設定する
Section titled “Webhook を設定する”manage_webhooks の権限を持つ人なら誰でも、管理画面の「Webhook」(/admin/webhooks)で Webhook を設定できます。組み込みの admin ロールはこの権限を持っています。「Webhook を追加」でフォームが開きます。一覧で Webhook を選ぶとそのページが開き、テスト、有効化と無効化、変更、直近 14 日間の配送の確認と再送、新しい秘密の発行ができ、送り先 URL のホスト名を入力して削除することもできます。配送が失敗し続けているときと、サーバーが Webhook を無効にしたときは、ページにそう表示されます。履歴には、配送ごとのイベント、状態、試行回数、最後の試行と、送った本文が表示されます。本文には個人データが含まれることがあるので、そのイベントに必要な権限(下を参照)も持つ人にだけ表示されます。
- 送り先の URL、説明、購読するイベントを指定して Webhook を作ります。各イベントには、
manage_webhooksのほかにそれぞれの権限も必要です。通報にはmanage_reports、登録、アカウント、モデレーションの措置、異議申し立てにはmanage_accounts、ドメインへの措置にはmanage_domains、カスタム絵文字にはmanage_custom_emojis、エラーのグループにはmanage_errorsが必要です。 公開投稿には追加の権限はいりません。権限を持っていないイベントは選べません。 - 秘密(
whsec_...)は、Webhook を作ったときに一度だけ表示されます。受け取り側に設定してください。もう一度表示することはできません。 - Webhook のページで「テスト送信」を選んで
webhook.testを送り、配送の一覧でそれが届いたことを確かめます。
Webhook の作成、変更、削除、有効化、無効化、秘密の作り直しは監査ログに記録されます。対象は説明と URL のホスト名で表示され、URL そのものは記録されません。
秘密を作り直す
Section titled “秘密を作り直す”「新しい秘密を作る」は新しい秘密を作り、一度だけ表示します。その後 24 時間は古い秘密でもメッセージに署名する(webhook-signature に 2 つの署名が入る)ので、その間に受け取り側を新しい秘密に切り替えられます。秘密は kernel.Sealer で封をしてからデータベースに保存されます。その鍵は KEK です。
失敗と再配送
Section titled “失敗と再配送”- 送り先が
2xx以外を返した場合、15 秒以内に応答しない場合、または到達できない場合は、5 秒後、5 分後、30 分後、2 時間後、5 時間後、10 時間後、10 時間後にメッセージを再送します(合計 8 回、約 27 時間)。すべての試行を使い切った配送は失敗したジョブになり、配送の一覧の「もう一度送る」で同じwebhook-idのまま再送できます。 - 送り先が
410 Goneを返した場合、その Webhook はすぐに無効になります。 - 最初の失敗から 72 時間成功せず、20 回以上続けて失敗した送り先は、サーバーが無効にします。監査ログに
systemによるwebhook_disabledの記録が残り、manage_webhooksを持つ全員にアプリ内の通知が届きます(メールで通知を受け取ることを選んだ人にはメールも届きます)。 - 管理画面の一覧には、続けて失敗した回数と、サーバーが Webhook を無効にした理由(
goneまたはfailing)が表示されます。送り先を直したら、Webhook をもう一度有効にしてください。無効だった間のメッセージは再送されません。 - メッセージと配送は 14 日後に削除されます(固定)。本文には、通報のコメントのような個人データが含まれます。
内部ネットワークの送り先
Section titled “内部ネットワークの送り先”配送は、外向き HTTP の SSRF ガードを通ります。既定では、https(ポート 443 と 80)で公開のアドレスにしか届きません。同じホストの n8n や VPC 内のチャットのような内部の送り先に送るには、ホスト名、IP アドレス、CIDR をカンマ区切りで設定 webhook_allowed_destinations(環境変数 MY_WEBHOOK_ALLOWED_DESTINATIONS。設定リファレンスを参照)に並べます。
MY_WEBHOOK_ALLOWED_DESTINATIONS=n8n.internal,10.0.0.0/8- ガードの対象から外れるのは、並べた送り先への、Webhook の配送だけです。連合、メディア、リンクのプレビューは変わりません。対象から外れた送り先には、
httpや任意のポートも使えます。 - ホスト名は、どのアドレスに解決されても許可されます。CIDR は、URL がその範囲の IP アドレスを指しているときに許可されます。その範囲に解決されるホスト名を使う場合は、ホスト名も並べてください。
- この設定を変えられるのは、サーバーにアクセスできる運用者だけです。管理画面の権限だけでは内部ネットワークに届きません。
- ガードが拒否した送り先への試行は、配送の一覧に
forbidden_destinationと表示されます。 - 開発用の設定
http_allow_private_networksは、Webhook も含め、あらゆる用途でガードを外します。
LLM とコーディングエージェント向け:llms.txt,llms-full.txt, llms-small.txt