Webhookコールバック

Flows APIでフローをトリガーすると、GitLabは指定したWebhookにフローのライフサイクルイベントを送信できます。これにより、APIをポーリングしてフローのステータスを確認する代わりに、フローの開始時、完了時、または失敗時に対応できます。

プロジェクトまたはグループでWebhookを使用できます。子プロジェクトはWebhookを継承します。これは、トップレベルグループのWebhookが、そのグループ内のすべてのプロジェクトのフローを処理することを意味します。

前提条件

Webhookがフローイベントを受信するには、以下の前提条件が満たされていることを確認してください:

• プロジェクトまたはグループ用にWebhookが作成されており、そのWebhookでコールバックが有効になっている。
• Webhookは、フローが実行されるプロジェクトまたはグループ、あるいはそのプロジェクトまたはグループの祖先グループのいずれかに属している。
• WebhookがシステムWebhookではないこと。

Webhookのコールバックを有効にする

前提条件:

• プロジェクトのWebhookの場合、プロジェクトのメンテナーまたはオーナーロールが必要です。
• グループWebhookの場合、グループのオーナーロールを持っている必要があります。

Webhookのコールバックを有効にするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 左側のサイドバーで、設定 > Webhooksを選択します。
3. 新しいWebhookを追加を選択するか、既存のWebhookの場合は編集を選択します。
4. GitLab Duo Agent Platformの下で、このWebhookにDuoフローイベントを送信チェックボックスを選択します。
5. Webhookを追加または変更を保存を選択します。

duo_flow_callback_enabled属性は、プロジェクトWebhook APIまたはグループWebhook APIで設定することもできます。いずれかのAPIを使用してWebhookをリストし、コールバックを有効にしたWebhookのIDを見つけます。

コールバックを有効にするために必要なロールは、Webhookにのみ適用されます。Webhookを参照するフローをトリガーするユーザーは、それらを必要としません。

フローのコールバックを受信する

前提条件:

• フローの前提条件を満たしている必要があります。

コールバックを受信するには、フローをトリガーするときに、Webhook IDをcallback_hook_id属性として渡します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "5",
    "goal": "Fix the failing pipeline by correcting the syntax error in .gitlab-ci.yml",
    "workflow_definition": "developer/v1",
    "start_workflow": true,
    "callback_hook_id": 42,
    "client_reference": "run-abc123"
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

GitLabが送信するイベントと各ペイロードの構造については、GitLab Duoフローイベントを参照してください。

コールバックをリクエストと関連付ける

オプションのclient_reference属性を使用して、コールバックとフローをトリガーしたリクエストを関連付けます。GitLabは、そのフローのすべてのコールバックでその値をエコーバックし、解釈しません。

エンドポイントでのコールバックの処理

コールバックがGitLabからのものであることを確認してから、それに対してアクションを実行してください。コールバックには他のすべてのWebhookイベントと同じヘッダーが含まれるため、Webhookに署名トークンを設定し、署名を検証してください。

GitLabは同じイベントを複数回配信する可能性があるため、エンドポイントを冪等にしてください。エンドポイントが成功またはリダイレクト応答を返さない場合、GitLabはバックオフ付きで最大5回配信を再試行します。再試行では元のペイロードのevent_idが繰り返されるため、処理済みのevent_id値を保存し、すでに確認したイベントは無視してください。再試行が尽きると、GitLabはそのイベントの配信を停止します。

繰り返される配信失敗はWebhookの失敗制限にカウントされ、GitLabはWebhookを自動的に無効にすることができます。Webhookが一時的に無効になっている場合、GitLabはそのWebhookのフローイベントを保持し、無効期間が終了した後に配信します。GitLabはイベントを最大3回保持します。Webhookがまだ無効になっている場合、GitLabはイベントを配信しません。GitLabは、完全に無効になっているWebhookにはフローイベントを送信しません。フローイベントを再度受信するには、Webhookを再度有効にしてください。

配信試行ごとに、GitLabはWebhookのコールバックがまだ有効になっていることを確認します。フローの実行中にコールバックをオフにすると、GitLabはキューに入っているイベントや保留中の再試行を含め、そのフローのイベントの送信を停止します。

GitLabが何を送信し、エンドポイントが何を返したかを確認するには、Webhookリクエスト履歴を表示します。最近のイベントセクションには、過去2日間にWebhookに対して行われたすべてのリクエストが表示されます。このセクションには配信試行のみが表示されるため、Webhookが無効になっている間にGitLabが保留したイベントや配信しなかったイベントは含まれません。

関連トピック

• GitLab Duoフローイベント
• Flows API
• Webhook