Webhook

Webhook は、Nodaro とほかのシステムを双方向につなぎます。Webhook トリガー（Webhook Trigger）ノードは、どのシステムからでも呼び出して実行を開始できる URL を、ワークフローに与えます。スケジュールトリガー（Schedule Trigger）は、それをタイムテーブルどおりに実行します。Webhook 出力（Webhook Output）ノードは、実行の結果を自分のサーバーに送信します。Nodaro が自分からこちらを呼び出すことはありません。実行が終わったことを知るには、それをポーリングするか、Webhook 出力ノードでワークフローを終えてください。

エンドポイント

HTTP 呼び出しでワークフローを開始する

curl -s -X POST "https://app.nodaro.ai/v1/webhooks/$WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse in a storm", "imageUrl": "https://example.com/lighthouse.jpg"}'

各 Webhook トリガーは、1 分あたり 10 リクエストを受け付けます。この上限は、API トークンの上限とは別です。

呼び出し元としてよくあるのは、顧客の登録時にオンボーディング動画を開始する決済システム、リリースノートの要約を求めるコードリポジトリ、新しい記事を公開するコンテンツシステム、ノーコードの自動化ツールなどです。

トリガーによる実行の範囲

• 何かに接続されたトリガーは、自分の分岐だけを実行します。トリガーより後ろにあるノードと、それらのノードが入力として必要とするすべてのノードです。
• どこにも接続されていないトリガーは、ワークフロー全体を実行します。
• そのため、1 つのワークフローに複数のトリガーを置き、それぞれに自分の分岐を開始させることができます。
• 「接続」とは、ほかのノードに値を渡すものすべてを指します。線で結んだ接続、グループ（Group）の中にあるノード、またはフィールドのマッピングです。
• エディター、API、公開したアプリからの実行は、トリガーによる制限を受けません。常に実行する範囲を、そのまま実行します。

API で手動作成したトリガーは、どのノードも指定しません。この場合 Nodaro は、キャンバス上の唯一の Webhook トリガーを使います。2 つある場合は、ワークフロー全体が実行されます。

URL を秘密にする

トークンが唯一の認証情報なので、URL を持っている人は誰でも実行を開始でき、あなたのクレジットを消費できます。組織のワークスペースにあるワークフローでは、実行の代金はワークスペースの予算から支払われます。URL を共有した相手は誰でも、そのクラスやチームのクレジットを消費できます。

Webhook、スケジュール、Telegram のいずれからの自動実行でも、実行の前に、トリガーの作成者がまだそのワークフローを実行できるかどうかが確認されます。権限付与が取り消された、メンバーシップが停止された、またはワークスペースがアーカイブされたなどの理由で実行できなくなっていた場合、自動化は停止します。この場合、ワークフローの実行履歴には、コード run_requires_authenticated_member を伴う失敗が 1 件表示されます。

API でトリガーを管理する

トリガーノードは、ワークフローを保存すると自分自身を登録します。4 つのルートが、それらを直接管理します。

• GET /v1/workflows/<id>/triggers は、ワークフローのトリガーを一覧表示します。
• PATCH /v1/workflow-triggers/<id> は、{ "isActive": false } でトリガーを一時停止し、true で再開します。ノードに属するトリガーでは、次に保存したときにノード自身のスイッチが再び適用されるので、後々まで残したい変更にはノードのスイッチを使ってください。送信した config は、保存済みの内容にマージされます。変更する項目だけを送信してください。トリガーとノードの紐付けと、実行回数は保持されます。
• POST /v1/workflows/<id>/sync-triggers は、ワークフローの保存済みバージョンから、トリガーノードを登録し直します。エディターは、保存するたびにこれを呼び出し、編集権限を持つ人なら誰でも呼び出せます。レスポンスは { "data": { "synced": …, "created": …, "updated": …, "removed": … } } です。
• POST /v1/workflow-triggers は、どのノードにも属さないトリガーを作成します。そのため、ワークフローを保存しても、変更されたり削除されたりすることはありません。トリガーは誰も見ていない状態で実行されるものなので、作成には、ワークフローの実行と同じ権限が必要です。

スケジュール

スケジュールトリガーは、ワークフローをタイムテーブルどおりに実行します。スケジュールはルールのリストで、いずれかのルールが現在の分と一致するたびに、ワークフローが実行されます。

スケジュールをオンにする

スケジュールトリガーノードは、データが "active": true（ノードのスイッチ）を示している間だけ実行されます。API、SDK、MCP で active なしに書き込まれたノードは、一時停止中の状態で登録されます。エディターのスイッチとスケジュールボタンは、同じフィールドを設定します。テンプレートのエクスポートにこのフィールドが含まれることはないため、インポートしたスケジュールは必ず一時停止の状態で始まります。

スケジュールを手動で作成する

{
  "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
  "type": "schedule",
  "config": {
    "rules": [
      { "kind": "days", "every": 1, "hour": 9, "minute": 0 },
      { "kind": "weeks", "every": 2, "weekdays": [1, 3], "hour": 18, "minute": 30 }
    ],
    "timezone": "Asia/Jerusalem"
  }
}

これを POST /v1/workflow-triggers に送信します。スケジュールトリガーノードが保存するのも、これと同じ形の config です。

• N 日、N 週、N か月ごとは、いずれも固定された起点から数えます。週は月曜日に始まるため、保存し直しても、スケジュールが実行される日がずれることはありません。
• cron ルールでは、日と曜日の組み合わせも含め、すべてのフィールドが一致する必要があります。一部の cron ツールでは、日と曜日はどちらか一方が一致すれば実行されます。7 は、0 と同じく日曜日を意味します。
• 範囲外の値には 400 が返されます。サーバーが認識できないタイムゾーンでも同様です。
• 手動で作成するトリガーでは、古い形式も引き続き使えます。5m、1h、1d のような interval や、cron 文字列です。これらで保存されたスケジュールトリガーノードは、ルールに変換されます。

スケジュールの実行の仕組み

• サーバーは、すべてのスケジュールを 1 分ごとに確認し、いずれかのルールがその分に一致すると、ワークフローを実行します。
• 同じ分が 2 回実行されることはありません。再起動や時刻の変更をまたいでも同様です。時刻の切り替えで飛ばされた分は、その日はスキップされます。
• ワークフローの前回の実行がまだ続いている場合、その分はスキップされます。
• 実行できないノードは、実行不可の状態になります。たとえば、式のない cron ルールや、認識できないタイムゾーンです。何も推測されないので、ノードを修正して、もう一度保存してください。

結果を自分のサーバーに送信する

Webhook 出力ノードは、そのノードに渡された結果を、設定したパラメーターとともに、POST リクエストとして自分の URL に送信します。パラメーターのタイプは、トリガーと同じ text、imageUrl、videoUrl、audioUrl です。メディアの値は、Nodaro が保存したファイルの URL で、自分のサーバーからダウンロードできます。

自分のエンドポイントがエラーを返すと、ノードは失敗し、そのエラーが実行の履歴に表示されます。https の URL を使ってください。

リクエストにキーを付けて送信する

多くのエンドポイントは、ヘッダーにキーが含まれたリクエストしか受け付けません。ヘッダー名とキーを、Web アプリの連携 › HTTP 認証情報で認証情報として一度だけ保存し、ノードで選びます。キーが、ワークフロー、エクスポート、テンプレートに含まれることはありません。

キーを保存するときは、それを使える範囲を選びます。

API トークンや OAuth トークンで開始した実行、Webhook トリガーによる実行、API で作成したスケジュールによる実行、公開したアプリからの実行は、あなたとして動作しますが、あなた自身が開始したものではありません。そうした実行のためには、認証情報をロックしてください。ロックしていない認証情報は、送信する代わりに、わかりやすいメッセージを出してノードを失敗させます。ロックした認証情報が送信されるのは、ノードの URL がそのアドレスと一致するときだけで、別のアドレスへのリダイレクトには従わず、キーが暗号化されていない http で送信されることもありません。

認証情報を付けている場合、ノードは自分のエンドポイントからの応答の本文を保持も表示もせず、扱うのはステータスコードだけです。認証情報は Web アプリでのみ管理します。認証情報のルートは、トークンに対して 403 in_app_only を返します。アプリの公開や、ほかの人が実行できるワークフローの共有は、サブワークフロー内のものも含め、送信に使うすべての認証情報が、ノードの送信先のアドレスにロックされるまで、409 credential_unbound を返します。

API での実行はコールバックなし

API から開始した実行は、終わっても URL を呼び出しません。結果を知る方法は、2 つあります。

• ポーリングする。GET /v1/workflow-executions/:id で実行を追跡するか、GET /v1/jobs/:id/status で 1 つのノードのジョブを追跡します。実行とジョブを参照してください。
• ワークフローに知らせてもらう。結果を自分のサーバーに送信する Webhook 出力ノードで、ワークフローを終えます。