概要
Webhook は、特定のリポジトリイベントによってトリガーされる HTTP コールバックです。イベントが発生すると、Diversion は設定されたエンドポイント URL に、リクエストボディにイベントの詳細を含めた POST リクエストを送信します。主な特長
- イベント駆動の通知: リポジトリイベントに対するリアルタイム通知
- セキュアな配信: リクエストの真正性を検証するための HMAC-SHA256 署名
- 信頼性の高い配信: 指数バックオフによる自動再試行
- 柔軟な構成: Webhook ごとに特定のイベントタイプにサブスクライブ可能
- 管理者専用の管理: リポジトリの管理者アクセスが必要
サポートされているイベント
現在、Diversion は以下の Webhook イベントをサポートしています:Webhook の管理
Webhook は Web アプリケーションから管理できます。アクセスにはリポジトリの管理者権限が必要です。Web インターフェース
プロフィールアバター → Your organizations → 設定サイドバーで Repositories を選択し、リポジトリ列で Webhooks を選択します。その列の上部にあるリポジトリピッカーでリポジトリを選択します。
Webhook を作成する
- “Create Webhook” をクリック
- Webhook の詳細を入力:
- Name: Webhook の分かりやすい名前
- Description: Webhook の目的の任意の説明
- Endpoint URL: イベントの送信先となる HTTPS URL
- Secret: 署名検証用の Webhook シークレット(未指定の場合は自動生成)
- Events: Webhook をトリガーするイベントを選択
- “Create” をクリックして Webhook を保存

Webhook シークレット
Webhook シークレットは、リクエスト検証用の HMAC-SHA256 署名の生成に使用されます。シークレットは次を満たす必要があります:- 24〜75 文字の長さ
- データベースに暗号化して保存
- Webhook 作成時のみ表示
whsec_<base64-encoded-random-bytes> 形式で暗号学的に安全な 32 バイトのシークレットを生成します。
Webhook ペイロード
すべての Webhook ペイロードは一貫した構造に従います:Commit Created イベントのペイロード
Review Created イベントのペイロード
Review Merged イベントのペイロード
リクエスト署名の検証
すべての Webhook リクエストには、検証用の署名ヘッダーが含まれます:webhook-id: メッセージの一意識別子webhook-timestamp: リクエストのタイムスタンプ(Unix エポック秒)webhook-signature: HMAC-SHA256 署名(形式:v1,base64signature)
署名検証の例
Diversion は Webhook 署名検証のリファレンス実装を提供しています。以下は Python での例です:Webhook の配信
Diversion は、以下の機能により Webhook の信頼性の高い配信を保証します:- 自動再試行: 失敗した配信は指数バックオフで再試行されます
- 配信状況の追跡: Webhook の配信状況を監視できます
- レート制限: 送信先サーバーが過負荷にならないようにします
- サーキットブレーキング: 失敗し続けるエンドポイントを一時的に無効化します
配信保証
- Webhook は少なくとも 1 回配信されます
- イベントは順不同で届くことがあります
- イベントの順序付けには
timestampフィールドを使用してください idフィールドを利用して、冪等なハンドラーを実装してください
Webhook のテスト
署名検証の実装をテストするには:- 既知のシークレットでテスト用の Webhook を作成する
- 上記の検証コード例を使用する
- リファレンスの AWS Lambda 実装と比較する
ベストプラクティス
- HTTPS エンドポイントを使用する: セキュリティ上、HTTP エンドポイントはサポートされていません
- 署名を検証する: 本番環境では常に Webhook の署名を検証してください
- 再試行に対応する: Webhook ハンドラーを冪等にしてください
- 迅速に応答する: 30 秒以内に 2xx ステータスを返してください
- キューでの処理: 長時間実行タスクの場合は、作業をキューに入れて即座に応答してください
- 失敗を監視する: Webhook 配信の失敗に対するアラートを設定してください
トラブルシューティング
よくある問題
-
Webhook がトリガーされない
- Webhook が有効かどうかを確認する
- イベントタイプのサブスクリプションを確認する
- リポジトリへの管理者アクセスがあることを確認する
-
署名検証に失敗する
- 正しいシークレットを使用しているか確認する
- タイムスタンプが許容範囲(5 分)内であることを確認する
- 署名の形式と解析を確認する
-
配信の失敗
- エンドポイントが公開アクセス可能であることを確認する
- SSL/TLS 証明書の問題を確認する
- エンドポイントが 2xx ステータスコードを返すことを確認する
- サーバーログでエラーを確認する
デバッグのヒント
- 初期テストには webhook.site などの Webhook テストツールを使用する
- Webhook ハンドラーでデバッグログを有効化する
- 想定されるペイロード形式で curl を使ってテストする
- 配信の問題を調査するためのサポートが必要な場合は サポートまでご連絡ください
セキュリティに関する考慮事項
- シークレット管理: Webhook シークレットは安全に保管し、コード内に記述しないでください
- ペイロード検証: 処理前にすべての Webhook データを検証してください
- レート制限: Webhook エンドポイントにレート制限を実装してください
- 認証: Webhook 署名を唯一の認証手段として使用してください
- HTTPS のみ: Webhook 配信には常に HTTPS エンドポイントを使用してください
Discord Webhook の統合
現時点では、Discord Webhook との直接連携はサポートされていません。ただし、Zapier や Pipedream のようなミドルウェアサービスを Discord と当社のプラットフォームの橋渡しとして使えば、Discord を接続できます。Pipedream を使って Discord Webhook を統合する
-
Pipedream をセットアップする
- Pipedream アカウントと新しいプロジェクトを作成する
- プロジェクトに名前を付け、Create Project をクリックする
-
ワークフローを作成する
- + New → Workflow を選択する
- ワークフローに名前を付け、“Send error notifications” のチェックを外し、Create Workflow をクリックする
-
トリガーを追加する
- Add Trigger をクリック → New HTTP / Webhook Requests を選択する
- Save and Continue をクリックする
-
Discord アクションを追加する
- トリガーの下の + シンボルをクリック → Discord を検索して選択する
- Send Message を選択する
- Discord アカウントを選択する
- Discord にログインし、サーバーとチャンネルを選択する
- メッセージを入力し(例: “New commit!”)、アクションを閉じる
- リポジトリ名、作成者、ブランチ、コミット ID、コミットメッセージ、コミットへのリンクを含む、より詳細なメッセージのテンプレートは次のとおりです:
- commit created イベントのペイロードから利用可能な他のフィールドにアクセスして、メッセージをさらにカスタマイズできます
-
テストとデプロイ
- Test をクリックしてメッセージが Discord に表示されることを確認する
- トリガーをクリック → Webhook URL をコピーする
- Diversion アプリで Webhook を設定する際、この URL を Payload URL として使用する
- Deploy をクリックしてワークフローを有効化する
- Diversion に移動し、この URL を Diversion に貼り付けて Webhook を追加する
-
Diversion で Webhook を設定する
- Diversion デスクトップアプリまたは Web UI を開く
- プロフィールアバター → Your organizations → 設定サイドバーで Repositories を選択し、リポジトリ列で Webhooks を選択します。その列の上部にあるリポジトリピッカーでリポジトリを選択します。
- Add Webhook をクリック
- Payload URL フィールドに、Pipedream からコピーした Webhook URL を貼り付ける
- その他の Webhook 詳細を入力する
- Add webhook をクリックして Webhook を有効化する

