メインコンテンツまでスキップ

Webhook 通知

Takumi API では、診断などのワークフロー完了時に Webhook で通知を受け取ることができます。これにより、ポーリングを行わなくてもワークフローの完了を検知し、結果の取得や後続処理を自動的に開始できます。

ワークフロー完了イベント​

ワークフローの実行が完了すると、指定した Webhook エンドポイントに以下の形式で HTTP POST リクエストが送信されます。イベントの type は api.workflow_run.exited です。

{
  "type": "api.workflow_run.exited",
  "timestamp": "2000-01-01T00:00:00Z",
  "data": {
    "workflow_id": "whitebox-assessment",
    "workflow_run_id": "TWR..."
  }
}

data.workflow_run_id を使ってワークフロー実行を特定し、/o/{org_id}/workflows/{workflow_id}/describe エンドポイントで結果を取得できます。

Webhook エンドポイントの指定方法​

ワークフロー実行 API (/o/{org_id}/workflows/{workflow_id}/dispatch) のリクエストボディで notification.webhook_endpoint_ids にエンドポイント ID を指定すると、そのワークフロー完了時に通知が送られます。

{
  "input": { /* ... */ },
  "notification": {
    "webhook_endpoint_ids": ["WH..."]
  }
}

Webhook の仕様​

イベントが発生した場合に、指定された Webhook エンドポイントに対して HTTP POST リクエストが送信されます。

リクエストボディは以下の構造を持ちます。

{
  "type": "{イベント種別}",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {/* イベントに応じたデータ */}
}

Webhook エンドポイントは 10 秒以内に HTTP 2xx ステータスコードを返すことで、リクエストの受信成功を示す必要があります。ステータスコードが 3xx の場合は失敗として扱われ、リダイレクト先にリクエストは送られません。

リクエスト送信に失敗した場合（非 2xx レスポンス、タイムアウト、ネットワークエラーなど）、本サービスは自動的にリトライを行います。

Webhook の配送は at-least-once であり、同一イベントが複数回配送される場合があります。各リクエストには webhook-id ヘッダーが付与されており、同一の webhook-id を持つリクエストは同一イベントの再送です。エンドポイントは webhook-id を用いて冪等に実装することをお勧めします。

署名の検証​

受信したリクエストが確かに本サービスから送信されたものであることを検証するため、受信時に必ず署名を検証してください。 本サービスは Standard Webhooks 仕様に準拠したリクエストの署名方式を採用しています。

以下は TypeScript での実装例です。

import { Webhook } from "standardwebhooks";

const wh = new Webhook(signingSecret);

// リクエストヘッダーと本文を渡して署名を検証する
wh.verify(requestBody, {
  "webhook-id": req.headers.get("webhook-id"),
  "webhook-timestamp": req.headers.get("webhook-timestamp"),
  "webhook-signature": req.headers.get("webhook-signature"),
});

const payload = JSON.parse(requestBody);

Webhook エンドポイントをセットアップする​

Webhook エンドポイントを登録する​

設定 > Webhook エンドポイント を開き、「新しい Webhook エンドポイントを登録」 から受信先の URL と説明を入力して登録します。

登録が完了すると、エンドポイント ID（WH... 形式）と署名シークレットが表示されます。

警告

署名シークレットはこの画面でしか確認できません。この画面を閉じる前に必ずコピーして安全な場所に保管してください。 紛失した場合は、「署名シークレットをローテーション」で再発行できます。

テスト送信で動作確認する​

受信サーバーが起動できたら、ワークフローを実行する前に Webhook が正しく届くかを確認しましょう。 設定 > Webhook エンドポイント でエンドポイント行の ... メニューから 「テストメッセージを送信」 を選択すると、テスト用のペイロードが送信されます。

サーバー側でリクエストを受信し、HTTP 2xx を返せていれば準備完了です。

署名シークレットをローテーションする​

シークレットを再生成したい場合は、エンドポイント行の ... メニューから 「署名シークレットをローテーション」 を選択します。

ローテーションのあと 24 時間は、本サービスは Webhook 通知時に新旧両方のシークレットで署名し、複数の署名を Standard Webhooks 仕様 に従ってリクエストに含めます。すなわち、24 時間は「古いシークレットで署名検証をする Webhook 受信サーバー」「新しいシークレットで署名検証をする Webhook 受信サーバー」の両方が、本サービスからの正当な Webhook 通知を受理します。従って、受信サーバーの設定を新しいシークレットに更新する作業を 24 時間以内に行えば、Webhook の受信を一切中断せずにシークレットを更新できます。

手順の例を以下に示します。

  1. ローテーションを実行し、新しい署名シークレットを取得する
  2. 受信サーバーの環境変数・設定ファイルを新しいシークレットに書き換え、サーバーを再起動する
  3. テスト送信で動作を確認する
  4. (24 時間経過以降、本サービスからの Webhook 通知には新しいシークレットでの署名のみが含まれる)
に最終更新