Webhook トリガー

Webhook トリガー（Webhook Trigger）ノードは、ほかのシステムがワークフロー専用の Webhook のアドレスに HTTP POST リクエストを送ったときに、ワークフローを開始します。コンテンツ管理システム、フォーム、自動化ツール、自分のコードからワークフローを実行するのに使います。リクエストでは、プロンプトや画像の URL などの値を実行に渡せます。トリガー自体は無料です。

使いどころ

• コンテンツ管理システムで新しい記事が公開されたときに、動画を生成します。
• 商品写真など、ほかのアプリから送られてくる画像を処理します。
• HTTP POST リクエストを送れる自動化ツールやスクリプトから、ワークフローを開始します。
• 自分のコードで制御するコンテンツ制作のワークフローを作ります。

クイックスタート

出力パラメーター

各パラメーターは、パラメーター名がそのまま付いたノードの出力になります。出力は、そのキーの値をテキストとして運びます。本文にないキーの出力は、空になります。

パラメーターがない場合、ノードの出力は、本文全体を運ぶ payload の 1 つだけです。

リクエストを送る

Webhook のアドレスに JSON 本文を POST します。本文のキーは、パラメーターの名前です。

curl -X POST "https://app.nodaro.ai/v1/webhooks/<token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A lighthouse at dawn, slow push-in", "imageUrl": "https://example.com/lighthouse.jpg"}'

セルフホスティング環境では、https://app.nodaro.ai の代わりに、自分の環境のアドレスを使います。

応答のステータスで、何が起きたかがわかります。

アドレスとトークン

• 保存するとアドレスが作成される：ノードを追加してワークフローを保存すると、Nodaro がランダムな 64 文字のトークンと、POST /v1/webhooks/<token> というアドレスを作成します。最初に保存するまでは、設定パネルに「ワークフローを保存すると、このトリガーの URL が作成されます」と表示されます。
• 設定パネルからコピーする：保存後は、パネルの Webhook URL に完全なアドレスが、コピーボタンと一緒に表示されます。その下には短縮したトークンが、専用のコピーボタンと一緒に表示されます。
• ノードには短縮したアドレスが表示される：キャンバス上のノードには、…/v1/webhooks/a1b2c3d4•••• のように、トークンの先頭部分だけを含むアドレスが表示されます。そのため、キャンバスのスクリーンショットからトークンが知られることはありません。
• アドレスが見えるのは所有者だけ：アドレスは、ワークフローの所有者のものです。ワークフローを編集できるほかの人には、アドレスの代わりに、保存を案内する上記のメッセージが表示されます。
• アドレスは変わらない：トークンは一度だけ作成され、その後に何度保存しても保持されます。そのため、ほかのシステムに渡したアドレスは使い続けられます。
• ノードを削除するとアドレスは無効になる：Webhook トリガーを削除して保存すると、アドレスは使えなくなります。
• アドレスは API で読み取る：GET /v1/workflows/<id>/triggers は、各トリガーのアドレスを /v1/webhooks/<token> という形式のパスとして、トークンと一緒に返します。config.nodeId がノードの ID と一致するトリガーが、このノードのトリガーです。

このアドレスは誰でもアクセスできる公開のアドレスで、トークンが唯一の保護の手段です。アドレスを知っている人は誰でもワークフローを開始でき、すべての実行の料金はワークフローの所有者に請求されます。アドレスは秘密にしてください。

制限

• トークンごとに 1 分間に 10 リクエスト：それを超えるリクエストには、ステータス 429 が返されます。
• 一度に 1 つの実行：ワークフローの実行中に届いた新しいリクエストには、ステータス 409 が返されます。

Webhook による実行の範囲

ノードに接続されているトリガーは、自身の分岐だけを実行します。分岐とは、トリガーの後ろにあるノードと、それらのノードが入力として必要とするすべてのノードです。何にも接続されていないトリガーは、ワークフロー全体を実行します。そのため、1 つのワークフローに、Webhook トリガーとスケジュールトリガー（Schedule Trigger）のように複数のトリガーを置き、それぞれに自分の分岐を開始させることができます。

ノードが接続されているとみなされるのは、線で接続されている場合、トリガーが入力を渡すグループ（Group）の中にある場合、フィールドのマッピングで結び付いている場合です。エディターからの手動実行、API からの実行、公開済みアプリの実行は、トリガーの分岐に限定されることはありません。

クレジット

Webhook トリガーは無料です。各実行では、実行したノードの分の料金が、ワークフローの所有者に請求されます。

ヒント

• 名前を一致させる：ほかのシステムが送るキーの名前を、大文字と小文字も含めて正確に使います。
• 1 回のリクエストで試す：本番のシステムを接続する前に、curl でリクエストを 1 回送ってみます。
• 結果を送り返す：ワークフローの最後に Webhook 出力（Webhook Output）を置くと、結果を自分のサーバーに送信できます。
• スケジュールでも実行する：スケジュールトリガーを追加すると、同じワークフローを決まった時刻に実行できます。

API の詳細は、Webhook を読んでください。