# Webhook

> Webhook トリガーの URL で任意のシステムからワークフローを開始し、API でスケジュールを作成し、Webhook 出力で結果を自分のサーバーに送信します。

Source: https://nodaro.ai/ja/docs/developers/api/webhooks

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

Workflow: 外部のシステムが Webhook トリガーの URL を呼び出すと、画像生成が実行され、Webhook 出力が画像の URL を自分のサーバーに送信します。

- Webhook トリガー → 画像生成 (プロンプト)
- 画像生成 → Webhook 出力

## エンドポイント
| メソッド | パス | 説明 |
| --- | --- | --- |
| `POST` | `/v1/webhooks/:token` | 実行を開始します。公開のルートで、パス内のトークンが認証情報です。 |
| `GET` | `/v1/workflows/:id/triggers` | ワークフローのトリガーを返します。各 Webhook の URL とトークンを含みます。 |
| `PATCH` | `/v1/workflow-triggers/:id` | `isActive` でトリガーを一時停止または再開するか、スケジュールの `config` を変更します。 |
| `POST` | `/v1/workflow-triggers` | どのノードにも紐付かないトリガーを、手動で作成します。 |
| `POST` | `/v1/workflows/:id/sync-triggers` | ワークフローの保存済みバージョンから、トリガーノードを登録し直します。 |

## HTTP 呼び出しでワークフローを開始する
### Webhook トリガーを追加する
[Webhook トリガー](https://nodaro.ai/docs/nodes/automate/webhook-trigger)ノードをワークフローに追加します。**出力パラメーター**で、呼び出し元が送信する値ごとに、パラメーターを 1 つ追加します。各パラメーターには、リクエストの JSON ボディのキーと一致する**名前**と、**タイプ**（`text`、`imageUrl`、`videoUrl`、`audioUrl` のいずれか）があります。パラメーターは、それを使うノードに接続します。

### ワークフローを保存する
保存すると、エンドポイントが作成されます。Nodaro が 32 バイトのトークンを発行し、`POST /v1/webhooks/<token>` を登録します。これは、エディター、API、SDK、インポート、MCP のいずれでワークフローを保存した場合でも起こります。トークンは一度だけ発行され、その後は保持されるので、外部のシステムに渡した URL は、その後何度保存してもそのまま使えます。ノードを削除すると、URL は無効になります。

### URL を読み取る
`GET /v1/workflows/<id>/triggers` は、ワークフローのトリガーを返します。各 Webhook の `webhookUrl` と `webhookToken` を含みます。`webhookUrl` は `/v1/webhooks/<token>` というパスなので、その前に自分の Nodaro のアドレスを付けてください。`config.nodeId` がノードの ID と一致するトリガーが、その Webhook トリガーノードのものです。一覧に表示されるのは、自分が所有するワークフローのトリガーだけです。

エディターでは、ノードの設定パネルの **Webhook URL** に、同じアドレスが完全な形で、コピーボタンとともに表示されます。

### 呼び出す
JSON ボディを付けて `POST` を送信します。`Authorization` ヘッダーは必要ありません。URL 内のトークンが認証情報です。

```bash
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"}'
```

このボディが、トリガーのペイロードになります。各パラメーターは、同じ名前のキーを読み取り、そのタイプによって値の渡し先が決まります。`imageUrl` は画像の入力に、`videoUrl` は動画の入力に渡されます。

各 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`** は、どのノードにも属さないトリガーを作成します。そのため、ワークフローを保存しても、変更されたり削除されたりすることはありません。トリガーは誰も見ていない状態で実行されるものなので、作成には、ワークフローの実行と同じ権限が必要です。

## スケジュール
[スケジュールトリガー](https://nodaro.ai/docs/nodes/automate/schedule-trigger)は、ワークフローをタイムテーブルどおりに実行します。スケジュールは**ルール**のリストで、いずれかのルールが現在の分と一致するたびに、ワークフローが実行されます。

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

### スケジュールを手動で作成する
```json
{
"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` です。

| `config` フィールド | 意味 |
| --- | --- |
| `rules` | 1 つ以上のルールです。いずれかのルールが一致すると、ワークフローが実行されます。 |
| `timezone` | ルールを読み取る基準となる時計で、`Asia/Jerusalem` のようなゾーン名で指定します。省略すると UTC になります。 |
| `maxExecutions` | この回数だけ実行すると停止します。スケジュールは登録されたままなので、続けるには回数を増やすか、空にしてください。 |

| `kind` | フィールド | 実行されるタイミング |
| --- | --- | --- |
| `minutes` | `every`（1〜59） | 毎時、0 分、N 分、2N 分…の時点 |
| `hours` | `every`（1〜23）、`minute` | 毎日 0 時、N 時、2N 時…の、指定した分 |
| `days` | `every`（1〜31）、`hour`、`minute` | 暦日で N 日ごとの、指定した時刻 |
| `weeks` | `every`（1〜52）、`weekdays`（0 が日曜日、6 が土曜日）、`hour`、`minute` | 指定した曜日の、N 週ごと |
| `months` | `every`（1〜12）、`dayOfMonth`（1〜31）、`hour`、`minute` | N か月ごとの、指定した日。月の日数が足りない場合は、その月の最終日 |
| `cron` | `cron`（5 フィールドの式） | 式に一致するたび |

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

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

## 結果を自分のサーバーに送信する
[Webhook 出力](https://nodaro.ai/docs/nodes/publish/webhook-output)ノードは、そのノードに渡された結果を、設定したパラメーターとともに、`POST` リクエストとして自分の URL に送信します。パラメーターのタイプは、トリガーと同じ `text`、`imageUrl`、`videoUrl`、`audioUrl` です。メディアの値は、Nodaro が保存したファイルの URL で、自分のサーバーからダウンロードできます。

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

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

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

| 選択肢 | 機能する場面 |
| --- | --- |
| **すべてのアドレス**（ロックなしの認証情報） | 自分で開始した実行です。エディターからの実行と、エディターで設定したスケジュールです。 |
| **1 つのアドレスのみ**（ロックされた認証情報） | すべての実行で機能しますが、送信先はそのアドレス、または許可されていればその配下のパスに限られます。 |

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 つのノードのジョブを追跡します。[実行](https://nodaro.ai/docs/developers/api/executions)と[ジョブ](https://nodaro.ai/docs/developers/api/jobs)を参照してください。
- **ワークフローに知らせてもらう。**結果を自分のサーバーに送信する Webhook 出力ノードで、ワークフローを終えます。

## Frequently asked questions

### Webhook で Nodaro のワークフローを開始するには、どうすればよいですか？

Webhook トリガー（Webhook Trigger）ノードを追加してパラメーターを定義し、ワークフローを保存します。保存すると、POST /v1/webhooks/ の後にトークンが続く形式の URL が作成されます。パラメーター名と一致するキーを持つ JSON ボディを送信するだけで、ほかの認証は必要ありません。

### 実行が終わったとき、Nodaro は自分のサーバーを呼び出しますか？

自動では呼び出しません。実行またはそのジョブをポーリングするか、Webhook 出力（Webhook Output）ノードでワークフローを終えてください。実行がそのノードに達すると、結果が自分の URL に送信されます。

### Webhook の URL は、共有しても安全ですか？

パスワードと同じように扱ってください。URL 内のトークンが唯一の認証情報なので、それを持っている人は誰でも実行を開始し、あなたのクレジット、またはワークスペースの予算を消費できます。各トリガーは、1 分あたり 10 リクエストまで受け付けます。

### API でワークフローをスケジュール実行するには、どうすればよいですか？

スケジュールトリガー（Schedule Trigger）ノードで、データの active を true に設定して保存するか、POST /v1/workflow-triggers に、ルールとタイムゾーンから成る config を指定してスケジュールを作成します。Nodaro は、すべてのスケジュールを 1 分ごとに確認します。

### API で作成したスケジュールトリガーが実行されないのは、なぜですか？

スケジュールトリガーは、データの active が true の間だけ実行されます。API、SDK、MCP でこのフィールドなしに書き込まれたノードは、一時停止の状態で登録されます。フィールドを設定して、もう一度保存してください。