n8nのWebhook Triggerを理解する｜外部イベントでWorkflowを起動する基本

n8nのWorkflowは、決めた時刻に起動するだけではありません。外部サービスで注文、フォーム送信、機器アラートなどのイベントが発生した瞬間に起動することもできます。

その入口になるのがWebhook nodeです。

外部サービスでイベント発生
→ Webhook URLへHTTP request
→ n8nがrequestを受信
→ Workflowを開始
→ 必要に応じてresponseを返す

Webhookを理解すると、n8nに専用Trigger nodeがないサービスでも、Webhook送信機能があればイベントを起点に連携できます。

今日の到達点

• Webhookとpollingの違いを説明できる
• GET／POSTなどのHTTP methodを受信側の視点で理解できる
• Test URLとProduction URLを使い分けられる
• headers、query、params、bodyの格納先を確認できる
• Workflowの処理結果を適切なHTTP responseとして返せる
• 公開Webhookに必要な認証と入力検証を説明できる

Webhookは外部イベントを受け取る入口

Webhookは、イベントが起きた側から指定URLへHTTP requestを送る仕組みです。

たとえばフォームサービスが送信完了時にn8nのWebhook URLへPOSTすれば、n8nは受け取った回答を使って通知やデータ登録を開始できます。

Webhook nodeはTrigger nodeなので、通常はWorkflowの先頭に置きます。

Webhook
→ 入力内容を検証
→ データを整形
→ 通知・登録・API連携
→ response

Webhookは受信したデータを起点に処理を始めるだけでなく、Workflowの結果を呼び出し元へ返すこともできます。そのため、小さなAPI endpointのように使うことも可能です。

Webhookとpollingの違い

Webhookとpollingは、どちらも外部の変化を検知する方法ですが、データを確認する方向が違います。

Webhookではイベント発生側がrequestを送るため、変更を比較的すぐ処理でき、不要な定期問い合わせも減らせます。一方、送信元がWebhookに対応していることと、n8nへ到達できるURLが必要です。

Pollingは相手側にWebhook機能がなくてもAPIから一覧を取得できれば構成できますが、確認間隔による遅延やAPI rate limitを考える必要があります。

Webhook nodeで設定するもの

HTTP Method

Webhook nodeでは、DELETE、GET、HEAD、PATCH、POST、PUTを選択できます。

学習では次の2つを押さえれば十分です。

• GET：URLへアクセスし、主にqueryから値を渡す
• POST：JSONやform dataなどをrequest bodyへ入れて送る

nodeに設定したmethodと、送信側のmethodは一致させます。POSTとして待ち受けているURLへGETしても、想定したWebhookは起動しません。

標準設定では、1つのWebhook nodeが受け付けるmethodは1つです。現在のn8nではSettingsのAllow Multiple HTTP Methodsを有効にすると、複数methodを受け付け、method別のoutputへ分ける構成も可能です。

最初の実習ではmethodを1つに固定した方が、データの流れを追いやすいでしょう。

Path

PathはWebhook URLの末尾を構成します。初期状態では衝突を避けるため、ランダムなpathが生成されます。

固定pathやroute parameterも設定できます。

/orders/:orderId

この場合、URLの該当部分がparamsへ入ります。ただし、推測しにくいURLは補助的な対策であり、認証の代わりにはなりません。

Test URLとProduction URL

Webhook nodeにはTest URLとProduction URLがあります。見た目が似ていますが、用途と有効になる条件が異なります。

Test URLを使う場合は、先にListen for test eventを選択して待受状態にしてからrequestを送ります。公式ドキュメントでは、test webhookの待受時間は120秒です。時間切れになったら、再びlisten状態にします。

Production URLはWorkflowをPublishすると登録されます。Production URLへ届いたデータはeditorへ直接表示されないため、Executionsから対象executionを開いて確認します。

開発中：Test URL + Listen for test event
運用中：Production URL + Published Workflow

外部サービスへ登録するURLをTest URLのままにすると、listenしている短い間しか動きません。反対に、構築中からProduction URLだけを使うと、入力データをeditorで観察しにくくなります。

現在の詳しい挙動は、n8n公式のWebhook workflow developmentで確認できます。

requestデータはどこへ入るか

Webhook nodeが受信したrequestは、主に次の構造で後続nodeへ渡されます。

{
  "headers": {
    "content-type": "application/json"
  },
  "params": {},
  "query": {
    "source": "practice"
  },
  "body": {
    "name": "Pump A",
    "pressure_mpa": 10
  }
}

• headers：Content-Typeや送信元が付けたheader
• query：URLの?source=practiceなどの値
• params：Pathで定義した:orderIdなどのroute parameter
• body：POSTなどで送られたJSONやform data

たとえばPOSTされた機器名は、後続nodeから次のように参照できます。

{{ $json.body.name }}

queryのsourceなら次のとおりです。

{{ $json.query.source }}

実際の構造は、送信側のContent-Typeやpayloadによって変わります。式を先に決めるのではなく、Test URLで実データを受け取り、Webhook nodeのOUTPUTをJSON表示してpathを確認してください。

POST requestを送る最小実習

最小Workflowは次の構成です。

Webhook（POST）
→ Edit Fields
→ Respond to Webhook

Webhook nodeをPOSTに設定してTest URLを表示し、Listen for test eventを選択します。別のterminalから次のようなrequestを送ります。

TEST_WEBHOOK_URL='ここへ実際のTest URLを一時的に設定'

curl --request POST "$TEST_WEBHOOK_URL?source=practice" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Pump A","pressure_mpa":10}'

この例では、sourceはquery、nameとpressure_mpaはbodyへ入ります。

実際のWebhook URLは記事、チャット、スクリーンショット、公開repositoryへ残さないでください。

responseを返す方法

Webhook nodeのRespondでは、requestを送った相手へ、いつ何を返すかを選びます。

Immediately

Workflowを開始した時点でresponseを返します。後続処理の完了を相手が待つ必要がない場合に向いています。

{
  "accepted": true
}

メール送信や大きなデータ処理など、結果を同期的に返す必要がない処理では、早く受付responseを返すと送信元のtimeoutを避けやすくなります。

When Last Node Finishes

最後に実行されたnodeの出力をresponseとして返します。Workflowで加工した結果をそのまま返す、小さなAPIに向いています。

処理が長い場合は、呼び出し元やネットワーク側のtimeoutに注意が必要です。n8n CloudではWebhookが100秒以内に応答しない場合、Cloudflareの524で失敗する可能性があります。

Using Respond to Webhook Node

Webhook node側でUsing ‘Respond to Webhook’ Nodeを選び、Workflowの途中にRespond to Webhook nodeを置きます。

このnodeでは次のようなresponseを指定できます。

• JSON
• text
• binary file
• redirect
• response code
• response headers
• response bodyなし

条件分岐ごとに異なるresponseを返したい場合にも便利です。

Respond to Webhook nodeは最初のincoming itemを使って1回実行されます。複数itemsを返す場合はAll Incoming Itemsを使うか、Aggregate nodeで1 itemへまとめるなど、期待するresponse構造を明確にします。

詳細はn8n公式のRespond to Webhook nodeで確認できます。

公開Webhookを守る

Production URLは外部から到達できる入口です。URLを知っているだけで重要な処理を実行できる設計にしないでください。

Webhook nodeでは、NoneのほかBasic auth、Header auth、JWT authを選べます。送信元が対応する方式に合わせてcredentialを設定します。

さらに、用途に応じて次を検討します。

• IP(s) Allowlistで送信元を限定する
• Allowed Originsでbrowserからのcross-origin requestを制御する
• payloadの必須field、型、許容値を検証する
• 外部IDを受け取っても、権限確認なしで削除や更新を実行しない
• 同じeventの再送に備え、event IDで重複実行を防ぐ
• requestやexecutionへpassword、tokenを不要に残さない
• 大量request、過大payload、長時間処理への制限を設ける

CORSはbrowserのcross-origin制御であり、server間requestを認証する仕組みではありません。URLの非公開化やOnly Run Ifだけに依存せず、認証と入力検証を組み合わせます。

公式仕様ではWebhookの最大payloadは16MBです。self-hostedではN8N_PAYLOAD_SIZE_MAXで変更できますが、上限を大きくする前にmemory、保存容量、処理時間、攻撃時の影響を検討します。

認証方法やIP allowlistを含む現在の設定項目は、n8n公式のWebhook nodeドキュメントで確認できます。

よくある失敗

Test URLが反応しない

Listen for test eventを選択した後、120秒以内にrequestを送ったか確認します。methodとURLも一致させます。

Production URLが反応しない

Workflowが保存・Publishされているか、外部サービスにProduction URLを登録したか確認します。

同じpathとmethodの組み合わせを、別のPublished Workflowが使用していないかも確認します。n8nでは同じpathとmethodの組み合わせを複数のWebhookへ登録できません。

bodyが空または想定と違う

送信側のContent-Type、実際のpayload、Webhook OUTPUTを確認します。JSONを送るなら通常はContent-Type: application/jsonを付けます。

localhostへ外部から届かない

localhostは通常、外部サービスから直接アクセスできません。self-hosted環境では公開URL、reverse proxy、TLS、n8nのWebhook URL設定を整える必要があります。

学習用tunnelを使う場合も、公開範囲と利用時間を限定します。

responseを返す前にtimeoutする

長時間処理を同期responseへ含めず、Immediatelyで受付結果を返して後続を非同期処理にする設計を検討します。必要なら、別endpointから処理状態を確認できる構成にします。

Webhook特有のエラーと確認方法は、n8n公式のWebhook common issuesにもまとめられています。

実務での考え方

Webhookを設計するときは、URLとpayloadだけでなく「受信契約」を決めます。

method: POST
authentication: header_auth
content_type: application/json
required_fields:
  - event_id
  - event_type
  - occurred_at
duplicate_key: event_id
success_response: 202

送信元は失敗やtimeoutによって同じeventを再送することがあります。同じrequestが2回来ても結果を二重登録しないidempotencyを意識すると、実運用で壊れにくくなります。

今日の実習で確認すること

• Webhook nodeをPOSTで作成する
• Test URLをlisten状態にする
• curlまたは別のHTTP clientからrequestを送る
• headers、query、params、bodyの格納先を確認する
• Respond to WebhookでJSONとstatus codeを返す
• Production URLの有効条件とExecutionsでの確認方法を説明する
• 記事と実際のUIに差があれば記録する

まとめ

Webhook nodeは、外部イベントを受け取ってWorkflowを開始する入口です。

外部イベント
→ 認証されたWebhook request
→ payloadを検証
→ Workflowで処理
→ 適切なresponse
→ Executionを記録

Test URLは構築中のデータ観察、Production URLはPublished Workflowの継続運用に使用します。requestではmethodとheaders、query、params、bodyを区別し、responseでは返す時点、内容、status codeを決めます。

Webhookは外部へ公開する入口だからこそ、認証、入力検証、重複防止、timeout対策まで含めて設計することが重要です。

参考資料

• n8n公式：Webhook node
• n8n公式：Webhook workflow development
• n8n公式：Webhook common issues
• n8n公式：Respond to Webhook node
• n8n公式：Webhook credentials