Webhook トリガー

Webhook は外部システム（GitHub、CI/CD、Lark、IoT、上流 API）が HTTP POST を通じて直接ワークフロー実行を起動できるようにします。推奨する方法: Webhook に WEBHOOK_TRIGGER 権限スコープを持つ API Key をバインドし、トリガーリクエストをこの Key で認証します。

Webhook の作成と API Key のバインド

1. コンソール → アカウント設定 → API キー で Key を新規作成し、scope で以下にチェックを入れます WEBHOOK_TRIGGER （詳細は以下を参照API Key と権限スコープ）
2. Webhook 一覧またはワークフロー詳細ページで Webhook を新規作成し、対象のワークフローを選択してこの Key をバインドします。作成者はワークフローに対する編集権限が必要で、バインドする Key は自分名義のものでなければなりません

管理 API（コンソールのログイン状態）を使うこともできます:

curl -X POST https://braidrun.com/api/webhooks \
  -H "Authorization: Bearer <console-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "GitHub Push Webhook",
    "apiKeyId": "<api-key-id>",
    "variableMapping": {
      "branch": "ref",
      "repo_name": "repo"
    }
  }'

レスポンスには一意の webhook-id が含まれ、トリガー URL は次のとおりです：

POST https://braidrun.com/api/webhooks/<webhook-id>/trigger

Webhook の数はプランに応じて決まります：Pro は 3 個、Team は 10 個です。

ワークフローをトリガーする

curl -X POST https://braidrun.com/api/webhooks/<webhook-id>/trigger \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/heads/main",
    "repo": "my-app"
  }'

認証情報の渡し方は 3 通りあり、サーバー側は以下の順序で識別します：

Authorization: Bearer dyk_<id>_<secret>      # 推荐
X-API-Key: dyk_<id>_<secret>                  # 无法自定义 Authorization 头时
POST .../trigger?api_key=dyk_<id>_<secret>    # 仅限无法设置 header 的场景

トリガーが成功すると、以下が返されます。

{
  "executionId": "exec_a3b9c8...",
  "webhookId": "<webhook-id>",
  "workflowId": "<workflow-id>",
  "status": "PENDING",
  "startedAt": 1735632891234
}

変数マッピング

variableMapping を設定しない場合、payload のトップレベルにある文字列・数値・真偽値のフィールドは、同名でワークフロー変数へ自動マッピングされます。ネストしたオブジェクトや配列は自動マッピングの対象になりません。

名前を変更したい場合は次を設定します variableMapping ：キーはワークフロー変数名、値は payload のトップレベルのフィールド名です。トップレベルのフィールドのみ対応し、ネストしたパスの取得には対応していません。

# Webhook 配置
"variableMapping": { "branch": "ref", "repo_name": "repo" }

# 触发 payload
{ "ref": "refs/heads/main", "repo": "my-app" }

# 工作流实际拿到的输入
{ "branch": "refs/heads/main", "repo_name": "my-app" }

payload にマッピング対象のフィールドが存在しない場合、その変数は注入されず、ワークフローテンプレート内のデフォルト値がそのまま有効になります（空文字列で上書きされることはありません）。

HMAC 署名（旧来の連携との互換用）

API Key を紐付けておらず、次を設定している secretKey Webhook は旧版の HMAC モードで動作します：トリガーリクエストは header に署名を含める必要があります：

X-Webhook-Signature: sha256=<hex(HMAC-SHA256(rawRequestBody, secretKey))>

署名 = HmacSHA256(rawRequestBody, secretKey) 、hex 文字列を出力します。sha256= の接頭辞は付けても付けなくても構いません。照合に失敗した場合は 401 を返します。

API Key を紐付けた Webhook は HMAC 署名を受け付けなくなります（secretKey フィールドに値が残っていても同様です）。API Key への移行は一方向です。どちらの認証も設定されていない Webhook はトリガー時に認証を検証せず、URL 自体が認証情報に相当するため、デバッグ段階でのみ利用することをおすすめします。

旧版のトリガーパス POST /api/webhook-trigger/{webhookId} は引き続き保持され、動作は同一です。新規連携では上記の正規パスを使用してください。

エラーレスポンス

一般的なアクセス シナリオ

• GitHub push — ブランチ名やコミット作者を変数にマッピングし、workflow が自動で build / test / deploy を行います
• CI 系统 — ビルドが完了 → Webhook が後続のリリース パイプラインをトリガー
• Lark / 飞书机器人 — 特定のコマンドを受信した後に操作バッチ処理をトリガーする
• IoT 上报 — デバイス アラーム → Webhook によりトラブルシューティング ワークフローがトリガーされ、アラームが収束します

管理エンドポイント

リスト GET /api/webhooks、更新 PUT /api/webhooks/{id}、削除 DELETE /api/webhooks/{id}、さらに GET /api/webhooks/{id}/stats がトリガー統計を返します。これらはいずれもコンソールのログイン状態が必要なインターフェースです。

サービス再開時

Webhook でトリガーされた execution がサービス再起動で中断された場合、自動では再開されません。payload は at-most-once で扱われ、プラットフォームは再送を行いません。manual_approval で承認待ちのまま停止している実行は例外で、承認後は通常どおり継続します。再実行が必要な場合は、上流から改めてトリガーリクエストを送信すればよく、新しい execution が作成されます。

関連ページ

• オープンプラットフォーム Webhook エンドポイント（承認コールバック）
• API Key と権限スコープ