Webhook でワークフローを起動する

DAG ワークフローには、外から POST するだけで起動できる URL を 1 本発行できます。手元のスクリプト、社内のサービス、ブラウザ拡張の「送る」ボタンなどから、ワークフローを走らせられます。

このページは意図的に 1 ページで完結させてあります。これだけを渡せば組み込める状態にするためです (人に渡す場合も、コーディング支援の AI に渡す場合も)。言語モデル向けのプレーンテキスト版は /ja/llms-dag-webhook.txt にあります。

この仕組みを 3 行で

ワークフローをプロジェクトに配置すると、その配置ごとに秘密のトークンを含む URL を発行できます。その URL に JSON オブジェクトを POST すると、body がそのまま start ノードの出力になり、下流のノードがその形のまま受け取ります。認証は URL に入っているトークンだけで、ヘッダも署名もありません。

始める前に必要な値

値	見た目	どこから
Webhook URL	`https://minionworkspace.com/api/dag/webhooks/<token>`	プロジェクトのワークフローを開き、Webhook トリガーの欄で有効化 → コピー

ホストは Minion を開いているオリジンと同じです。 ワークスペース ID もプロジェクト ID もパスには出てきません。パスは /api/dag/webhooks/<token> だけで、どこに届くかはトークンが決めます。
URL は「ワークフロー × プロジェクト」ごとに 1 本です。 同じワークフローを 2 つのプロジェクトに配置しているなら URL は別々で、どちらのプロジェクトのメンバー・ロール・コンテキストで走るかは URL が決めます。呼ぶ側がプロジェクトを指定することはできません。
トークンは 32 バイトの乱数 (base64url、43 文字) です。URL 全体が資格情報なので、環境変数に置いてください (例: MINION_WEBHOOK_URL)。NEXT_PUBLIC_・PUBLIC_・VITE_ を付けてはいけません。付けるとブラウザに配る JavaScript に埋め込まれます。
画面では URL のトークン部分が伏せられていますが、コピーは常にフルの URL をコピーします。発行時にしか読めない類のものではないので、無くしたら画面から取り直せます。

有効化・停止・作り直し

操作	起きること
有効化	トークンを発行して URL が使えるようになる
Rotate token	新しいトークンを発行。古い URL は即座に 404 になる。漏れたときはこれ
無効化	URL が無効になる。トークンは破棄されます

「一時停止」のつもりで無効化しないでください。 もう一度有効化すると別の URL が発行され、呼び出し側の設定を書き換える必要があります。

リクエスト

curl -i -X POST "$MINION_WEBHOOK_URL" \
  -H 'content-type: application/json' \
  -d '{"source": "chrome-extension", "url": "https://example.com/x/status/123"}'

認証

認証ヘッダはありません。 Authorization: Bearer ... も X-...-KEY も署名も使いません。 URL に入っているトークンが唯一の資格情報です。余分なヘッダを付けても読まれず、エラーにもなりません。

URL そのものが鍵なので、ログ・エラー通知・Referer・スクリーンショットに URL を出さない ようにしてください。

ヘッダ

ヘッダ	必須	備考
`Content-Type: application/json`	必須	無いと `415`。`application/json; charset=utf-8` も可
それ以外	—	読まれません

メソッドは POST だけです。GET などは 405 になります。

ボディ

決まった箱はありません。 title / body / url のような固定のフィールド名は定義されていません。好きなキーに好きな型 (文字列・数値・真偽値・配列・ネストしたオブジェクト) を入れて構いません。封筒 ({"payload": {...}} のような包み) も付けません。送ったオブジェクトが そのまま start ノードの output_data になり、下流のノードがその形で受け取ります。

制約	内容
トップレベルの型	JSON オブジェクト 1 つ。配列・`null`・数値・文字列は `400`
空ボディ	`400`。何も渡さないときも `{}` を送ってください
大きさ	1MB まで (`Content-Length` で判定、超えると `413`)

受け取り側が形を決めている場合がある

ワークフローの start ノードに input_contract が設定されているか、start から出るエッジに contract が貼られていると、body はその型を満たす必要があり、満たさなければ実行は 1 ノードも走らずに 400 で弾かれます。レスポンスの violations に、どのフィールドがどう違うかが入ります。

contract があるかどうかは、呼ぶ側からは事前に分かりません。 ワークフローを作った人に「start に contract があるか、あるならフィールド名と型」を聞いてください。設定されていなければ、どんなオブジェクトでも通ります。

レスポンス

成功

HTTP/1.1 201 Created

{ "execution_id": "3f0c…", "root_nodes": 1, "total_nodes": 7 }

201 は「受理して実行を作った」という意味で、完了ではありません。 ワークフロー本体はこの後ミニオン側で非同期に走ります。

外から進捗や結果を取る API はありません。 execution_id は HQ の画面で実行を特定するための ID で、実行の状態を返す API はログインセッションを要求するため、Webhook のトークンでは読めません。結果を呼び出し元に返したい場合は、ワークフローの側から自分のサービスを叩く (最後にスキルノードや script ノードで POST する) 形にしてください。

失敗

本文は必ず {"error": "<英語 1 行>"} です。contract 違反のときだけ violations 配列が付きます。 error はそのままボタンの title やトーストに出せる短さです。

status	`error` の例	意味・対処
`400`	`Request body must be a JSON object`	配列・スカラー・空ボディを送っている
`400`	`Invalid JSON body`	JSON として壊れている
`400`	`Payload violates start input contract "X"`	`violations[]` に違反箇所。送る形を直す
`400`	`Payload violates start outgoing edge contracts`	同上 (start の出力エッジ側の型)
`400`	`DAG workflow has no version` / `DAG workflow has empty graph`	ワークフローが未保存・空。作った人に連絡
`400`	`No PM minion assigned to project`	配置先プロジェクトに PM ロールのミニオンがいない
`404`	`Not found`	トークンが違う / Webhook が無効 / 配置が無効。3 つは区別されません (総当たり対策)
`409`	`Project is archived`	プロジェクトが凍結中。解除は人が HQ で行う
`413`	`Payload exceeds 1000000 bytes`	1MB 超
`415`	`Content-Type must be application/json`	ヘッダ不足
`500`	`Internal server error`	一時障害

4xx は送り直しても同じ結果です。 直してから送ってください。再送の対象は 5xx とタイムアウトだけですが、次の項を読んでからにしてください。

重複排除

ありません。 Idempotency-Key ヘッダは読みませんし、ボディにも重複排除用のフィールドはありません。同じ body を 2 回 POST すれば、実行が 2 本走ります。

タイムアウト時の自動再送が危ないのは、201 が返る前に切れても実行は作られている可能性があるためです。必要なら次のどちらかにしてください。

呼ぶ側で一意な値 ("source_id": "..." など) を body に入れ、ワークフロー側で処理済みかを見て弾く
自動再送をせず、失敗はユーザーに見せて手で押し直させる (拡張機能のボタンなら、たいていこれで足ります)

CORS

CORS ヘッダは返しません。 Content-Type: application/json の POST は必ずプリフライトを起こすため、Web ページの JavaScript から直接呼ぶとブラウザにブロックされます。 これは意図した挙動です — URL 全体が資格情報なので、ページに配る JS に置いてよいものではありません。

呼び出し元	可否
ブラウザ拡張の background / service worker (`host_permissions` に HQ のオリジンを追加)	可
サーバー・CLI・CI・ミニオン	可
Web ページのフロントエンドから直接	不可。自分のサーバーを経由してください

レート制限

アプリ側のレート制限はありません。 ただし 1 回の POST が実際にワークフローを 1 本走らせ、ミニオンの (課金対象の) 計算時間を消費します。ボタン連打がそのまま実行の山になるので、 送る側で二重送信を止めてください (送信中はボタンを無効化する、など)。

画像などのファイル

この口は JSON だけです。 multipart もバイナリも受け付けません。
URL を渡すのが素直です。 送信サイズが小さく済み、ワークフロー側のミニオンがその URL を取りに行けます。ただし取得に認証が要らない URL であること。ログインしないと見えない画像はミニオンからも取れません。
base64 で埋め込むこともできますが、1MB の上限に効きます。 base64 は約 1.37 倍になるため、実質 700KB 程度の画像が上限です。それを超えるものは URL か、先にドライブへ置く形にしてください。
送った body は実行の記録としてそのまま保存されます。base64 を送ると実行履歴も同じだけ太ります。

うまくいかないときは

404 から疑ってください。 有効化したか / Rotate した後の新しい URL か / そのワークフローの配置が有効か。この 3 つは区別されずに 404 になります。
201 が返るのに何も起きないように見えるときは、HQ の実行一覧を見てください。実行は作られていて、下流のノードがミニオンに拾われるのを待っている (または失敗している) はずです。
400 で violations が付いているなら、送る形の問題です。フィールド名・型・必須の過不足が具体的に書かれています。

他の起動方法

方法	ペイロード	備考
手動	画面で入力	HQ の実行ボタン
スケジュール (cron)	常に `{}`	最短 5 分間隔。プロジェクトの PM ミニオンが発火する
Webhook	POST した JSON オブジェクト	このページ