Skip to main content
Diversion は、リポジトリでイベントが発生したときに外部サービスに通知する Webhook をサポートしています。これにより、CI/CD システム、通知サービス、およびカスタム自動化ワークフローとの連携が可能になります。

概要

Webhook は、特定のリポジトリイベントによってトリガーされる HTTP コールバックです。イベントが発生すると、Diversion は設定されたエンドポイント URL に、リクエストボディにイベントの詳細を含めた POST リクエストを送信します。

主な特長

  • イベント駆動の通知: リポジトリイベントに対するリアルタイム通知
  • セキュアな配信: リクエストの真正性を検証するための HMAC-SHA256 署名
  • 信頼性の高い配信: 指数バックオフによる自動再試行
  • 柔軟な構成: Webhook ごとに特定のイベントタイプにサブスクライブ可能
  • 管理者専用の管理: リポジトリの管理者アクセスが必要

サポートされているイベント

現在、Diversion は以下の Webhook イベントをサポートしています:

Webhook の管理

Webhook は Web アプリケーションから管理できます。アクセスにはリポジトリの管理者権限が必要です。

Web インターフェース

プロフィールアバターYour organizations → 設定サイドバーで Repositories を選択し、リポジトリ列で Webhooks を選択します。その列の上部にあるリポジトリピッカーでリポジトリを選択します。 Webhook 管理インターフェース

Webhook を作成する

  1. “Create Webhook” をクリック
  2. Webhook の詳細を入力:
    • Name: Webhook の分かりやすい名前
    • Description: Webhook の目的の任意の説明
    • Endpoint URL: イベントの送信先となる HTTPS URL
    • Secret: 署名検証用の Webhook シークレット(未指定の場合は自動生成)
    • Events: Webhook をトリガーするイベントを選択
  3. “Create” をクリックして Webhook を保存
Webhook 作成フォーム

Webhook シークレット

Webhook シークレットは、リクエスト検証用の HMAC-SHA256 署名の生成に使用されます。シークレットは次を満たす必要があります:
  • 24〜75 文字の長さ
  • データベースに暗号化して保存
  • Webhook 作成時のみ表示
自動生成: シークレットが指定されていない場合、Diversion は 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 検証実装が、AWS Lambda 関数の例として利用できます。Webhook 署名検証について支援が必要な場合は、サポートまでご連絡ください

Webhook の配信

Diversion は、以下の機能により Webhook の信頼性の高い配信を保証します:
  • 自動再試行: 失敗した配信は指数バックオフで再試行されます
  • 配信状況の追跡: Webhook の配信状況を監視できます
  • レート制限: 送信先サーバーが過負荷にならないようにします
  • サーキットブレーキング: 失敗し続けるエンドポイントを一時的に無効化します

配信保証

  • Webhook は少なくとも 1 回配信されます
  • イベントは順不同で届くことがあります
  • イベントの順序付けには timestamp フィールドを使用してください
  • id フィールドを利用して、冪等なハンドラーを実装してください

Webhook のテスト

署名検証の実装をテストするには:
  1. 既知のシークレットでテスト用の Webhook を作成する
  2. 上記の検証コード例を使用する
  3. リファレンスの AWS Lambda 実装と比較する

ベストプラクティス

  1. HTTPS エンドポイントを使用する: セキュリティ上、HTTP エンドポイントはサポートされていません
  2. 署名を検証する: 本番環境では常に Webhook の署名を検証してください
  3. 再試行に対応する: Webhook ハンドラーを冪等にしてください
  4. 迅速に応答する: 30 秒以内に 2xx ステータスを返してください
  5. キューでの処理: 長時間実行タスクの場合は、作業をキューに入れて即座に応答してください
  6. 失敗を監視する: Webhook 配信の失敗に対するアラートを設定してください

トラブルシューティング

よくある問題

  1. Webhook がトリガーされない
    • Webhook が有効かどうかを確認する
    • イベントタイプのサブスクリプションを確認する
    • リポジトリへの管理者アクセスがあることを確認する
  2. 署名検証に失敗する
    • 正しいシークレットを使用しているか確認する
    • タイムスタンプが許容範囲(5 分)内であることを確認する
    • 署名の形式と解析を確認する
  3. 配信の失敗
    • エンドポイントが公開アクセス可能であることを確認する
    • SSL/TLS 証明書の問題を確認する
    • エンドポイントが 2xx ステータスコードを返すことを確認する
    • サーバーログでエラーを確認する

デバッグのヒント

  • 初期テストには webhook.site などの Webhook テストツールを使用する
  • Webhook ハンドラーでデバッグログを有効化する
  • 想定されるペイロード形式で curl を使ってテストする
  • 配信の問題を調査するためのサポートが必要な場合は サポートまでご連絡ください

セキュリティに関する考慮事項

  1. シークレット管理: Webhook シークレットは安全に保管し、コード内に記述しないでください
  2. ペイロード検証: 処理前にすべての Webhook データを検証してください
  3. レート制限: Webhook エンドポイントにレート制限を実装してください
  4. 認証: Webhook 署名を唯一の認証手段として使用してください
  5. HTTPS のみ: Webhook 配信には常に HTTPS エンドポイントを使用してください

Discord Webhook の統合

現時点では、Discord Webhook との直接連携はサポートされていません。ただし、Zapier や Pipedream のようなミドルウェアサービスを Discord と当社のプラットフォームの橋渡しとして使えば、Discord を接続できます。

Pipedream を使って Discord Webhook を統合する

  1. Pipedream をセットアップする
    • Pipedream アカウントと新しいプロジェクトを作成する
    • プロジェクトに名前を付け、Create Project をクリックする
  2. ワークフローを作成する
    • + NewWorkflow を選択する
    • ワークフローに名前を付け、“Send error notifications” のチェックを外し、Create Workflow をクリックする
  3. トリガーを追加する
    • Add Trigger をクリック → New HTTP / Webhook Requests を選択する
    • Save and Continue をクリックする
  4. Discord アクションを追加する
    • トリガーの下の + シンボルをクリック → Discord を検索して選択する
    • Send Message を選択する
    • Discord アカウントを選択する
    • Discord にログインし、サーバーとチャンネルを選択する
    • メッセージを入力し(例: “New commit!”)、アクションを閉じる
    • リポジトリ名、作成者、ブランチ、コミット ID、コミットメッセージ、コミットへのリンクを含む、より詳細なメッセージのテンプレートは次のとおりです:
    • commit created イベントのペイロードから利用可能な他のフィールドにアクセスして、メッセージをさらにカスタマイズできます
  5. テストとデプロイ
    • Test をクリックしてメッセージが Discord に表示されることを確認する
    • トリガーをクリック → Webhook URL をコピーする
    • Diversion アプリで Webhook を設定する際、この URL を Payload URL として使用する
    • Deploy をクリックしてワークフローを有効化する
    • Diversion に移動し、この URL を Diversion に貼り付けて Webhook を追加する
  6. Diversion で Webhook を設定する
    • Diversion デスクトップアプリまたは Web UI を開く
    • プロフィールアバターYour organizations → 設定サイドバーで Repositories を選択し、リポジトリ列で Webhooks を選択します。その列の上部にあるリポジトリピッカーでリポジトリを選択します。
    • Add Webhook をクリック
    • Payload URL フィールドに、Pipedream からコピーした Webhook URL を貼り付ける
    • その他の Webhook 詳細を入力する
    • Add webhook をクリックして Webhook を有効化する