Webhook API

フローの Webhook URL を呼び出して実行を開始する方法です。トリガーの設定方法は Webhook でフローを開始する を参照してください。

URL

https://<組織 ID>.<ドメイン>/triggers/<Webhook ID>

Webhook トリガーごとに専用の URL があり、トリガーの設定に Hook URL として表示されます。そこからコピーしてください。フローを複製またはインポートすると、コピー側には新しい URL が発行されます。

URL で実行が開始されるのは、フローが公開済みで、有効になっている間だけです。

認証

トリガーの Hook APIキー を Bearer トークンとして送ります。

Authorization: Bearer <Hook APIキー>

Authorization をほかの用途で使っている呼び出し元のために、X-Authorization: Bearer <Hook APIキー> も使えます。

メソッド

メソッド	ボディ
POST	リクエストボディに JSON オブジェクトを入れます。通常はこちらを使います。
GET	body または payload クエリパラメータに、URL エンコードした JSON オブジェクトを入れます。キーはヘッダーの代わりに token クエリパラメータでも送れます。

POST を使い、キーはヘッダーで送ってください。token に入れたキーを含め、クエリパラメータはサーバーやプロキシのログに残ることがあります。

リクエストボディ

Content-Type: application/json で JSON オブジェクトを送ります。ボディは空でも構いません。

curl -X POST 'https://<組織 ID>.<ドメイン>/triggers/<Webhook ID>' \
  -H 'Authorization: Bearer <Hook APIキー>' \
  -H 'Content-Type: application/json' \
  -d '{"orderId": "A-1001", "total": 4200}'

送ったオブジェクトはトリガーの出力になり、後続のステップでは orderId を $trigger.output.orderId で読めます。

送る内容	トリガーの出力
{"orderId": "A-1001"}	{"orderId": "A-1001", …}
{"data": {"orderId": "A-1001"}}	{"orderId": "A-1001", …}。最上位の data 項目は中身だけが使われます。
ボディなし	下の項目だけを持つ {…}。

出力には常に次の 2 項目が追加され、同じ名前の項目は上書きされます。

項目	値
triggerType	webhook
timestamp	トリガーが動いた時刻。1970 年からのミリ秒。

ボディは JSON オブジェクトでなければなりません。[1, 2] のようなリストは拒否されます。リストを送るときは {"items": [1, 2]} のように包んでください。

レスポンス

Webhook はリクエストを受け付けた時点で応答し、その後に実行が始まります。そのため、レスポンスにフローの結果が入ることはありません。

200 OK:

{
  "result": "ok",
  "details": {
    "message": "Workflow executed successfully",
    "organizationId": "01HAXD218S50F6YY4JF2F92FZF",
    "webhookId": "…",
    "runId": "…",
    "messageId": "…",
    "timestamp": 1744702070657,
    "requestId": "…"
  }
}

200 は、リクエストを受け取りキューに入れたことを示すだけです。フローが公開済みか、有効かは確認しません。そうでない場合も 200 が返りますが、実行は始まりません。実行されたかどうかは 実行履歴 で確認してください。

結果を受け取りたい場合は、フローの最後で、たとえば HTTP ステップ を使ってこちらのシステムを呼び出します。

エラー

エラー時は、error と details.message を持つ JSON が返ります。

{
  "error": "Unauthorized",
  "details": {
    "message": "Invalid authorization token",
    "type": "Authentication Error"
  }
}

ステータス	error	原因
400	Invalid request	URL に組織 ID または Webhook ID がない。
400	Invalid request body	ボディが JSON オブジェクトではない（リストなど）。details.errors に詳細が入ります。
401	Unauthorized	キーが送られていない、またはキーが正しくない。
500	Internal server error	ボディが正しい JSON ではない、またはリクエストを処理できなかった。ボディを確認してから再送してください。

関連ページ

• Webhook でフローを開始する
• Webhook ノード
• トリガー