Webhook
署名付きの job.completed と job.failed のイベントを自分のサーバーで受け取り、Webhook トリガーの URL でワークフローを開始し、スケジュールを作成して結果を送信します。
Webhook は、Nodaro とほかのシステムを双方向につなぎます。自分で登録した Webhook エンドポイントは、自分のジョブが終わるたびに署名付きのイベントを受け取るので、サーバーがポーリングする必要はありません。Webhook トリガーノードは、どのシステムからでも呼び出して実行を開始できる URL を、ワークフローに与えます。スケジュールトリガーは、それをタイムテーブルどおりに実行します。Webhook 出力ノードは、実行の結果を自分のサーバーに送信します。
エンドポイント
これらのルートは、Nodaro がジョブイベントを送るエンドポイントを管理します。自分のサーバーでジョブイベントを受け取るを参照してください。
| メソッド | パス | 説明 |
|---|---|---|
POST | /v1/webhook-endpoints | エンドポイントを登録します。レスポンスには、署名用のシークレットが 1 回だけ含まれます。 |
GET | /v1/webhook-endpoints | 自分のエンドポイントを新しい順に返します。シークレットが一覧に含まれることはありません。 |
GET | /v1/webhook-endpoints/:id | 1 つのエンドポイントです。 |
PATCH | /v1/webhook-endpoints/:id | url、events、description、isActive を変更します。 |
DELETE | /v1/webhook-endpoints/:id | エンドポイントと、その配信ログを削除します。 |
POST | /v1/webhook-endpoints/:id/rotate-secret | 署名用のシークレットを置き換えます。古いシークレットには猶予期間があります。 |
GET | /v1/webhook-endpoints/:id/deliveries | 配信ログを新しい順に返します。 |
GET | /v1/webhook-endpoints/:id/deliveries/:deliveryId | 1 件の配信です。 |
POST | /v1/webhook-endpoints/:id/test | テスト用の ping を送信します。 |
これらのルートは、ワークフローを開始し、そのトリガーを管理します。/v1/webhook-endpoints の下にはありません。
| メソッド | パス | 説明 |
|---|---|---|
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 | ワークフローの保存済みバージョンから、トリガーノードを登録し直します。 |
自分のサーバーでジョブイベントを受け取る
https のエンドポイントを登録すると、自分のジョブが終わるたびに、Nodaro がそこに POST を送信します。サーバーは、GET /v1/jobs/:id をポーリングせずに、生成が終わったことを知ることができます。各リクエストはエンドポイント独自のシークレットで署名され、サーバーが応答するまでバックオフしながら再試行され、エンドポイントの配信ログに記録されます。
エンドポイントを登録する
curl -s -X POST "https://app.nodaro.ai/v1/webhook-endpoints" \
-H "Authorization: Bearer $NODARO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/nodaro-webhook", "description": "order fulfilment"}'const { data: endpoint, secret } = await client.webhooks.create({
url: "https://example.com/nodaro-webhook",
description: "order fulfilment",
})
// Store `secret` (whsec_...) with your server's config: it is shown only once.
await client.webhooks.test(endpoint.id) // a ping, sent within secondsnodaro webhooks create --url https://example.com/nodaro-webhook
nodaro webhooks test <id> --waitレスポンスは { data, secret } とともに 201 です。シークレットは whsec_ で始まり、このレスポンスにしか含まれないので、すぐに保存してください。events は任意です。events でどちらか一方を指定しない限り、エンドポイントは両方のジョブイベントを受け取ります。
エンドポイントは、次のように読み取られます。
{
"id": "3f6c2a1e-8b4d-4c7a-9e1f-2d5b6a7c8e90",
"url": "https://example.com/nodaro-webhook",
"description": "order fulfilment",
"events": ["job.completed", "job.failed"],
"isActive": true,
"disabledReason": null,
"disabledAt": null,
"consecutiveFailures": 0,
"appId": null,
"secretCreatedAt": "2026-10-15T10:00:00Z",
"previousSecretExpiresAt": null,
"createdAt": "2026-10-15T10:00:00Z",
"updatedAt": "2026-10-15T10:00:00Z"
}イベント
| イベント | 送信されるとき |
|---|---|
job.completed | 自分のジョブが completed になったとき。レビューのために保留されたジョブ(pending_review)は、承認されたときにイベントを送信します。 |
job.failed | 自分のジョブが failed になったとき。 |
ping | POST /v1/webhook-endpoints/:id/test からのみ送信されます。エンドポイントがこれを購読することはありません。 |
ジョブの一覧にあるすべてのジョブが対象です。単体の生成も、ワークフローの実行内の各ノードのジョブも含まれます。キャンセルされたジョブは何も送信せず、pending や processing のような途中のステータスも何も送信しません。失敗した後で完了したジョブは、終わるたびに 1 つずつイベントを送信します。コンポーネントノードの実行内のジョブはジョブの一覧にないので、何も送信しません。実行を開始したノードが、その実行について報告します。
リクエスト
Nodaro は、Content-Type: application/json と次のヘッダーを付けて POST を送信します。
| ヘッダー | 値 |
|---|---|
Nodaro-Signature | t=<unix seconds>,v1=<hex> です。シークレットのローテーション中は、シークレットごとに 1 つの v1= が付きます。 |
Nodaro-Event | job.completed、job.failed、ping のいずれかです。 |
Nodaro-Delivery | 配信 ID で、このイベントのどの再試行でも同じです。 |
Nodaro-Webhook | エンドポイントの ID です。 |
Nodaro-Attempt | 最初の試行では 1、その後は 2、3 と続きます。 |
User-Agent | Nodaro-Webhooks/1 |
署名されるのは、タイムスタンプとボディだけです。振り分けと重複の排除は、Nodaro-Event や Nodaro-Delivery のヘッダーではなく、検証したボディの type と id で行ってください。
{
"id": "6f1d0c0e-1c7e-4d0a-9f2b-0a4e2f7b9c11",
"type": "job.completed",
"createdAt": "2026-10-15T10:00:04.512Z",
"data": {
"job": {
"id": "0b9a5c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d",
"status": "completed",
"progress": 100,
"job_type": "generate-image",
"input_data": { "type": "generate-image", "prompt": "a lighthouse at dusk" },
"output_data": { "imageUrl": "https://cdn.nodaro.ai/images/0b9a5c1d.png" },
"error_message": null,
"error_hint": null,
"credit_status": "committed",
"credits": 40,
"credits_charged": 40,
"credits_held": 40,
"credits_released": 0,
"source": "sdk",
"session_id": null,
"title": null,
"created_at": "2026-10-15T10:00:00.000Z",
"completed_at": "2026-10-15T10:00:04.512Z"
}
}
}idは配信 ID です。イベントとエンドポイントごとに一意で、どの再試行でも同じなので、これで重複を排除してください。createdAtは、ジョブがこのステータスになった日時です。data.jobは、GET /v1/jobs/:idが返す形のジョブで、最初の試行の時点の内容です。再試行では、まったく同じバイト列のボディが送られます。請求がまだ精算されていない場合、credits_chargedはcredit_status: "reserved"とともにnullのことがあります。最終的な値は、ジョブをもう一度読み取って確認してください。GET /v1/jobs/:idと同じく、credits_chargedにはジョブが実行したステップが含まれ、credits_heldはステップの確保を含む実行全体の確保額、credits_releasedは実行の中のすべての確保が精算された後に戻った額です(それまではnull)。ジョブのクレジットを参照してください。titleは、所有者が付けたジョブの名前です。名前が付くまではnullです。- イベントは最大 64 KB です。それより大きいジョブでは、まず
input_dataが、次にoutput_dataが省かれ、省かれたものがdata.omittedに示されます。ジョブ全体はGET /v1/jobs/:idにあります。 pingは"data": { "webhookId": "<endpoint id>" }を持ちます。
署名を検証する
v1 は、<t>.<raw body> の HMAC-SHA256 で、エンドポイントのシークレット全体(whsec_...、UTF-8)をキーにします。リクエストを信頼する前に、次の 3 点を確認してください。
- 署名が、受け取ったバイト列そのものと一致すること。先に JSON をシリアライズし直さないでください。
- タイムスタンプが最近のものであること。許容範囲は通常 5 分です。この確認で、傍受されたリクエストが後から再送されるのを防ぎます。
- この
idをまだ処理していないこと。
SDK では、@nodaro/sdk の verifyWebhookSignature がこれらを確認します。Web Crypto だけを使うので、Node 20 以降、Deno、Bun、Cloudflare Workers、Vercel Edge、ブラウザーで動作します。
import express from "express"
import { verifyWebhookSignature, WebhookSignatureError } from "@nodaro/sdk"
const app = express()
app.post("/nodaro-webhook", express.raw({ type: "application/json" }), async (req, res) => {
try {
const event = await verifyWebhookSignature({
payload: req.body, // the raw bytes
header: req.headers["nodaro-signature"],
secret: process.env.NODARO_WEBHOOK_SECRET!,
toleranceSeconds: 300,
})
if (event.type === "job.completed") {
await saveResult(event.data.job.id, event.data.job.output_data)
}
res.sendStatus(204) // any 2xx within 10 seconds counts as delivered
} catch (err) {
if (err instanceof WebhookSignatureError) return res.status(400).send(err.code)
throw err
}
})verifyWebhookSignature は、解析したイベントを返すか、WebhookSignatureError をスローします。その code は、missing_header、malformed_header、signature_mismatch、timestamp_outside_tolerance、invalid_payload、missing_secret、crypto_unavailable のいずれかです。
SDK を使わない場合の Node での例です。
import { createHmac, timingSafeEqual } from "node:crypto"
// rawBody: the request body as received (a Buffer or a string).
function verify(rawBody: Buffer | string, header: string, secret: string, toleranceSeconds = 300) {
const pairs = header.split(",").map((part) => part.trim().split("=", 2))
const t = pairs.find(([key]) => key === "t")?.[1]
const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest()
const matches = pairs.some(([key, value]) => {
if (key !== "v1") return false
const got = Buffer.from(value, "hex")
return got.length === expected.length && timingSafeEqual(got, expected)
})
return matches && Math.abs(Date.now() / 1000 - Number(t)) <= toleranceSeconds
}ローテーションの猶予期間中は、ヘッダーにシークレットごとの v1= が、新しいものから順に付きます。どれか 1 つが一致すれば、リクエストを受け入れてください。配信ログは、成功していない配信の正確なボディ(requestBody)を保持するので、失敗する検証をバイト単位で再現できます。
再試行
10 秒以内の 2xx の応答は、どれも配信済みとみなされます。それ以外はすべて試行の失敗です。3xx(リダイレクトはたどりません)、4xx、5xx、タイムアウト、応答しないアドレスです。その後、配信は再試行されます。
| 試行の後 | 次の試行まで |
|---|---|
| 1 | 30 秒 |
| 2 | 2 分 |
| 3 | 10 分 |
| 4 | 1 時間 |
| 5 | 6 時間 |
| 6 | 12 時間 |
| 7 | 24 時間 |
各待ち時間は、前後に最大 10% ずれます。8 回目の試行(最初の試行から約 43 時間後)の後、配信は最終的に失敗します。テスト用の ping は 1 回だけ試行されます。
- 配信は少なくとも 1 回です。サーバーが最初の試行を処理した後に、再試行が届くことがあります。たとえば、応答が遅すぎた場合です。配信の
idで重複を排除してください。 - イベントの順序は前後することがあります。1 つのエンドポイントには同時に最大 5 件、1 つのアカウントには最大 10 件の配信が送られます。届いた順序ではなく、
createdAtとジョブ自体のstatusを使ってください。 - まったく応答しないサーバーには、エンドポイントの休止が入ります。HTTP の応答がない試行が 5 回続くと、エンドポイントは 1 分間休止し、それが繰り返されるたびに休止は 2 倍に延び、最長で 1 時間になります。待機中の配信は試行回数を保持し、何らかの HTTP の応答があれば休止は終わります。
- Nodaro 側の問題は、あなたの側の失敗として数えられません。配信は数分待ってから、試行回数を使わずに再試行されます。その間、ログのエントリーには
signing_unavailableまたはjob_unreadableが表示されます。
自動停止
50 件の配信が続けて最終的に失敗すると、Nodaro はエンドポイントを停止します。isActive は false に、disabledReason は "consecutive_failures" になります。受信側を修正し、テスト用の ping で確認してから、PATCH /v1/webhook-endpoints/:id に { "isActive": true } を送ってエンドポイントを有効にしてください。これでカウントもリセットされます。成功した場合も同様です。
エンドポイントが停止している間は、自分で停止したか Nodaro が停止したかにかかわらず、そのエンドポイントのイベントは記録されません。すでに待機中の配信は、error: "endpoint_disabled" で failed になります。テスト用の ping は、引き続き送信されます。
配信ログ
GET /v1/webhook-endpoints/:id/deliveries は、エンドポイントの配信を新しい順に一覧表示します。デフォルトでは 1 ページ 20 件で、最大 100 件です。status(pending、delivered、failed のいずれか)で絞り込み、limit と cursor でページを取得します。レスポンスは { data, next } です。ログは 30 日間保持されます。
各配信は、event、jobId、status、attempts、受信側の最後の responseStatus、その responseBody の最初の 2 KB、durationMs、error、待機中であれば nextAttemptAt を持ちます。requestBody は送信した正確なボディで、配信が待機中の間か失敗した後に保持され、配信済みになると null になります。GET /v1/webhook-endpoints/:id/deliveries/:deliveryId は、たとえばテストでキューに入った ping など、1 件の配信を読み取ります。
error は、次のいずれかの値です。
error | 意味 |
|---|---|
http_<status> | サーバーがそのステータスで応答しました。 |
timeout | 10 秒以内に応答がありませんでした。 |
blocked_address | アドレスが、公開されたインターネットのアドレスに解決されません。Nodaro は接続する前に拒否しました。 |
connection_refused、connection_reset、tls_error、network_error | 接続に失敗しました。 |
endpoint_disabled | 配信の待機中に、エンドポイントが停止されました。 |
app_revoked | エンドポイントを登録した接続済みアプリを、取り消しました。 |
job_deleted | 送信できる前に、ジョブが削除されました。 |
attempts_exhausted | 最後の試行が、応答が記録される前に Nodaro 側で中断されました。 |
signing_unavailable、job_unreadable | Nodaro 側の問題です。配信は待機し、試行回数を使わずに再試行されます。 |
シークレットをローテーションする
POST /v1/webhook-endpoints/:id/rotate-secret は { secret, previousSecretExpiresAt } を返し、新しいシークレットはこのレスポンスにしか含まれません。それ以降は、再試行も含め、すべての配信に新しいシークレットで署名します。置き換えられたシークレットも、gracePeriodSeconds の間は並んで署名を続けます。デフォルトは 1 日で、最長 7 日です。これにより、途切れることなく受信側を更新する時間が得られます。漏えいした後など、古いシークレットをすぐに止めるには、{ "gracePeriodSeconds": 0 } を送ります。
ルールと上限
- 公開ホストの
httpsのみです。http://、localhost、プライベート、ループバック、リンクローカルのアドレス、.internalや.localで終わる名前のようにプライベートネットワーク内でしか使えない名前は、使えません。URL にユーザー名やパスワードを含めることもできません。アドレスは、試行のたびに解決し直されます。自分のマシンで受信するには、トンネルを使い、そのhttpsのアドレスを登録してください。 - 1 つのアドレスに 1 つのエンドポイントです。同じアドレスを 2 回登録すると、
409 url_takenが返されます。代わりに、1 つのエンドポイントで両方のイベントを購読してください。 - アカウントごとに 10 個のエンドポイントです。11 個目には
400 limit_reachedが返されます。 - 書き込みにはレート制限があります。作成、更新、削除、シークレットのローテーションは 1 分あたり 30 回、テスト用の ping は 1 分あたり 10 回です。
- エンドポイントを管理できるもの:ログイン中のセッション、個人用 API トークン、
jobs:readスコープを持つ接続済みアプリのトークンです。一部のワークフローに制限された個人用トークンでは管理できません。 - 接続済みアプリが登録したエンドポイント(
appIdが設定されています)は、そのアプリ自身が送信したジョブだけを、アプリへの許可にjobs:readが含まれている間だけ受け取ります。アプリが開始したワークフローの実行のジョブは含まれません。実行はGET /v1/workflow-executions/:idで追跡してください。アプリに見えるのは、自分で登録したエンドポイントだけです。あなたは、そのすべてを表示し、削除できます。 - セルフホスティング環境は自分のサーバーから送信し、
NODARO_ENCRYPTION_KEYが必要です。Docker Compose のスタックがこれを生成します。これがない場合、ルートは503 encryption_key_missingを返します。 - MCP では使えません。エンドポイントを登録すると、署名用のシークレットが返され、アカウント全体の配信が設定されます。これは AI エージェントではなく、アプリや CLI が行う操作です。
そのほかのエラー:アドレスやボディが正しくない場合は 400 validation_error、403 insufficient_scope、自分のものではない ID には 404 not_found、保存されているアドレスが現在のルールで受け付けられないエンドポイントには 409 url_invalid です。有効にしたりテストしたりする前に、その url を変更してください。409 secret_required は、署名の導入前に登録されたエンドポイントであることを示します。有効にしたりテストしたりする前に、シークレットをローテーションしてください。
HTTP 呼び出しでワークフローを開始する
Webhook トリガーを追加する
Webhook トリガーノードをワークフローに追加します。出力パラメーターで、呼び出し元が送信する値ごとに、パラメーターを 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 内のトークンが認証情報です。
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 つのワークフローに複数のトリガーを置き、それぞれに自分の分岐を開始させることができます。
- 「接続」とは、ほかのノードに値を渡すものすべてを指します。線で結んだ接続、グループの中にあるノード、またはフィールドのマッピングです。
- エディター、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 です。
config フィールド | 意味 |
|---|---|
rules | 1 つ以上のルールです。いずれかのルールが一致すると、ワークフローが実行されます。 |
timezone | ルールを読み取る基準となる時計で、Asia/Jerusalem のようなゾーン名で指定します。省略すると UTC になります。 |
maxExecutions | この回数だけ実行すると停止します。スケジュールは登録されたままなので、続けるには回数を増やすか、空にしてください。 |
retry | 任意。ノードの失敗時の再試行です:{ afterMinutes, maxAttempts, cheapLanesOnly }。failed または timed_out で終わったスケジュール実行は、終了から afterMinutes 後(5〜1,440、デフォルト 30)に、最大 maxAttempts 回(1〜5、デフォルト 3)もう一度実行されます。cheapLanesOnly(デフォルト true)の場合、その実行と再試行のモデル呼び出しは、モデルの開発元の直接のサービスに切り替わりません。省略したフィールドはデフォルトになります。再試行しない場合は retry を省略します。PATCH では、"retry": null で再試行をオフにします。スケジュールトリガーを参照してください。 |
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が返されます。サーバーが認識できないタイムゾーンや、範囲外のretryの値でも同様です。 - 再試行の実行は、
GET /v1/workflows/<id>/executionsでretry: { "attempt": 1, "maxAttempts": 3, "retryOf": "<failed execution id>" }付きで一覧表示されます。 - 手動で作成するトリガーでは、古い形式も引き続き使えます。
5m、1h、1dのようなintervalや、cron文字列です。これらで保存されたスケジュールトリガーノードは、ルールに変換されます。
スケジュールの実行の仕組み
- サーバーは、すべてのスケジュールを 1 分ごとに確認し、いずれかのルールがその分に一致すると、ワークフローを実行します。
- 同じ分が 2 回実行されることはありません。再起動や時刻の変更をまたいでも同様です。時刻の切り替えで飛ばされた分は、その日はスキップされます。
- ワークフローの前回の実行がまだ続いている場合、その分はスキップされます。
- 実行できないノードは、スイッチがオンでも一時停止のままで、ノードには実行不可と表示されます。たとえば、式のない
cronルールや、認識できないタイムゾーンです。何も推測されないので、ノードを修正して、もう一度保存してください。
結果を自分のサーバーに送信する
Webhook 出力ノードは、そのノードに渡された結果を、設定したパラメーターとともに、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 を返します。
エンドポイントを使わずに実行を追跡する
実行の結果を知る方法は、ほかに 2 つあります。
- ポーリングする。
GET /v1/workflow-executions/:idで実行を追跡するか、GET /v1/jobs/:id/statusで 1 つのノードのジョブを追跡します。実行とジョブを参照してください。 - ワークフローに知らせてもらう。結果を自分のサーバーに送信する Webhook 出力ノードで、ワークフローを終えます。
よくある質問
Webhook で Nodaro のワークフローを開始するには、どうすればよいですか?
Webhook トリガーノードを追加してパラメーターを定義し、ワークフローを保存します。保存すると、POST /v1/webhooks/ の後にトークンが続く形式の URL が作成されます。パラメーター名と一致するキーを持つ JSON ボディを送信するだけで、ほかの認証は必要ありません。
ジョブが終わったとき、Nodaro は自分のサーバーを呼び出しますか?
はい。POST /v1/webhook-endpoints で Webhook エンドポイントを登録すれば呼び出します。その後は、自分のジョブが終わるたびに、Nodaro が署名付きの job.completed または job.failed のイベントを自分の https の URL に送信し、約 43 時間再試行します。
Nodaro の Webhook イベントを検証するには、どうすればよいですか?
エンドポイントのシークレットで、タイムスタンプ、ドット、生のボディをつないだものの HMAC-SHA256 を計算し、Nodaro-Signature ヘッダーの v1 の値と比較します。タイムスタンプが最近のものであることも確認してください。SDK の verifyWebhookSignature は、その両方を行います。
Webhook の URL は、共有しても安全ですか?
パスワードと同じように扱ってください。URL 内のトークンが唯一の認証情報なので、それを持っている人は誰でも実行を開始し、あなたのクレジット、またはワークスペースの予算を消費できます。各トリガーは、1 分あたり 10 リクエストまで受け付けます。
API でワークフローをスケジュール実行するには、どうすればよいですか?
スケジュールトリガーノードで、データの active を true に設定して保存するか、POST /v1/workflow-triggers に、ルールとタイムゾーンから成る config を指定してスケジュールを作成します。Nodaro は、すべてのスケジュールを 1 分ごとに確認します。
API で作成したスケジュールトリガーが実行されないのは、なぜですか?
スケジュールトリガーは、データの active が true の間だけ実行されます。API、SDK、MCP でこのフィールドなしに書き込まれたノードは、一時停止の状態で登録されます。フィールドを設定して、もう一度保存してください。
関連ページ
Webhook トリガー
スケジュールトリガー
Webhook 出力
自動化
実行
最終更新