NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
REST API

Webhook

署名付きの job.completed と job.failed のイベントを自分のサーバーで受け取り、Webhook トリガーの URL でワークフローを開始し、スケジュールを作成して結果を送信します。

Webhook は、Nodaro とほかのシステムを双方向につなぎます。自分で登録した Webhook エンドポイントは、自分のジョブが終わるたびに署名付きのイベントを受け取るので、サーバーがポーリングする必要はありません。Webhook トリガーノードは、どのシステムからでも呼び出して実行を開始できる URL を、ワークフローに与えます。スケジュールトリガーは、それをタイムテーブルどおりに実行します。Webhook 出力ノードは、実行の結果を自分のサーバーに送信します。

プロンプトWebhook トリガーprompt, imageUrl画像生成Nano Banana ProWebhook 出力自分のサーバー
外部のシステムが Webhook トリガーの URL を呼び出すと、画像生成が実行され、Webhook 出力が画像の URL を自分のサーバーに送信します。

エンドポイント

これらのルートは、Nodaro がジョブイベントを送るエンドポイントを管理します。自分のサーバーでジョブイベントを受け取るを参照してください。

メソッドパス説明
POST/v1/webhook-endpointsエンドポイントを登録します。レスポンスには、署名用のシークレットが 1 回だけ含まれます。
GET/v1/webhook-endpoints自分のエンドポイントを新しい順に返します。シークレットが一覧に含まれることはありません。
GET/v1/webhook-endpoints/:id1 つのエンドポイントです。
PATCH/v1/webhook-endpoints/:idurl、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/:deliveryId1 件の配信です。
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/:idisActive でトリガーを一時停止または再開するか、スケジュールの 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 seconds
nodaro 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 になったとき。
pingPOST /v1/webhook-endpoints/:id/test からのみ送信されます。エンドポイントがこれを購読することはありません。

ジョブの一覧にあるすべてのジョブが対象です。単体の生成も、ワークフローの実行内の各ノードのジョブも含まれます。キャンセルされたジョブは何も送信せず、pending や processing のような途中のステータスも何も送信しません。失敗した後で完了したジョブは、終わるたびに 1 つずつイベントを送信します。コンポーネントノードの実行内のジョブはジョブの一覧にないので、何も送信しません。実行を開始したノードが、その実行について報告します。

リクエスト

Nodaro は、Content-Type: application/json と次のヘッダーを付けて POST を送信します。

ヘッダー値
Nodaro-Signaturet=<unix seconds>,v1=<hex> です。シークレットのローテーション中は、シークレットごとに 1 つの v1= が付きます。
Nodaro-Eventjob.completed、job.failed、ping のいずれかです。
Nodaro-Delivery配信 ID で、このイベントのどの再試行でも同じです。
Nodaro-Webhookエンドポイントの ID です。
Nodaro-Attempt最初の試行では 1、その後は 2、3 と続きます。
User-AgentNodaro-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 点を確認してください。

  1. 署名が、受け取ったバイト列そのものと一致すること。先に JSON をシリアライズし直さないでください。
  2. タイムスタンプが最近のものであること。許容範囲は通常 5 分です。この確認で、傍受されたリクエストが後から再送されるのを防ぎます。
  3. この 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、タイムアウト、応答しないアドレスです。その後、配信は再試行されます。

試行の後次の試行まで
130 秒
22 分
310 分
41 時間
56 時間
612 時間
724 時間

各待ち時間は、前後に最大 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>サーバーがそのステータスで応答しました。
timeout10 秒以内に応答がありませんでした。
blocked_addressアドレスが、公開されたインターネットのアドレスに解決されません。Nodaro は接続する前に拒否しました。
connection_refused、connection_reset、tls_error、network_error接続に失敗しました。
endpoint_disabled配信の待機中に、エンドポイントが停止されました。
app_revokedエンドポイントを登録した接続済みアプリを、取り消しました。
job_deleted送信できる前に、ジョブが削除されました。
attempts_exhausted最後の試行が、応答が記録される前に Nodaro 側で中断されました。
signing_unavailable、job_unreadableNodaro 側の問題です。配信は待機し、試行回数を使わずに再試行されます。

シークレットをローテーションする

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 フィールド意味
rules1 つ以上のルールです。いずれかのルールが一致すると、ワークフローが実行されます。
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フィールド実行されるタイミング
minutesevery(1〜59)毎時、0 分、N 分、2N 分…の時点
hoursevery(1〜23)、minute毎日 0 時、N 時、2N 時…の、指定した分
daysevery(1〜31)、hour、minute暦日で N 日ごとの、指定した時刻
weeksevery(1〜52)、weekdays(0 が日曜日、6 が土曜日)、hour、minute指定した曜日の、N 週ごと
monthsevery(1〜12)、dayOfMonth(1〜31)、hour、minuteN か月ごとの、指定した日。月の日数が足りない場合は、その月の最終日
croncron(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 でこのフィールドなしに書き込まれたノードは、一時停止の状態で登録されます。フィールドを設定して、もう一度保存してください。

最終更新

目次