n8n Webhook Tutorial:
10 Minutes to Your First Real Automation

What Is a Webhook in n8n (Actually)

A webhook is a URL that listens. That's it. When something happens elsewhere — a form submission, a Stripe payment, a GitHub push — it makes a POST request to that URL. n8n catches it and your workflow fires.

The key difference from a schedule trigger (which polls on a timer) is that webhooks are event-driven. They react to things as they happen. This is why they're the foundation of every serious automation stack: you're not asking "did anything happen?" every 5 minutes — you're being told the moment it does.

Webhooks are how I get instant Telegram alerts when a lead submits a form, when a Stripe payment goes through, and when someone pings my n8n agent endpoint. They fire within milliseconds of the event.

In n8n, you create a webhook by dropping in a Webhook node as your trigger. n8n gives you a URL. You paste that URL into whatever tool you want to react to. Done.

Step-by-Step: Your First Webhook Workflow

Let's build something real: a workflow that catches a form submission and sends you a Telegram message with the contact's name and email. This is the workflow I run on every lead capture form — it's three nodes, takes 8 minutes, and saves you hours of inbox checking.

curl -X POST "YOUR_TEST_URL_HERE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alex", "email": "alex@example.com", "message": "Interested in your services"}'

🔔 New Lead!

Name: {{ $json.contact_name }}
Email: {{ $json.contact_email }}
Message: {{ $json.message }}

Time: {{ $now.toISO() }}

How to Test Webhooks Without Exposing Localhost

This is where beginners get stuck. If you're running n8n locally (not cloud, not VPS), external tools can't reach your localhost URL. The form doesn't know where http://localhost:5678 is.

Three options, in order of preference:

Option 1: Use n8n Cloud for testing. n8n Cloud gives you a real HTTPS URL immediately. It's $20/month. If you're self-hosting but need to test external webhook triggers, spin up a free trial or pay the month.

Option 2: Cloudflare Tunnel (free, my recommendation for self-hosters). This creates a public HTTPS URL that tunnels to your local n8n instance. Setup:

# Install cloudflared
brew install cloudflare/cloudflare/cloudflared  # macOS
# or download binary from cloudflare.com/products/tunnel

# Create a quick tunnel (no account needed for testing)
cloudflared tunnel --url http://localhost:5678

# You'll get a URL like: https://random-words-here.trycloudflare.com
# Use that as your webhook base URL in n8n

The tunnel URL changes every restart. For permanent self-hosting, set up a named Cloudflare Tunnel with your domain. That's what I run — a Hetzner CX22 ($6/month) with Cloudflare Tunnel in front of it. All webhooks hit the public URL, tunnel routes to n8n. Solid, free on the Cloudflare side.

Option 3: ngrok. Same idea as Cloudflare Tunnel but ngrok is the original. Free tier has limits and the URL changes on restart. Works fine for development.

Handling Payload Data — The Part Most Tutorials Skip

This is the part that trips people up. The payload structure varies depending on what's sending it. Here's how it actually works in n8n:

The $json structure

When a webhook fires, n8n wraps the incoming data. How you reference it depends on where the data is:

• $json.body — the POST body (this is what you want 99% of the time)
• $json.headers — request headers (useful for auth tokens, content-type)
• $json.query — URL query parameters (for GET webhooks)
• $json.params — URL path parameters

So if Typeform sends {"form_response": {"answers": [...], "variables": {...}}}, you'd access the first answer as $json.body.form_response.answers[0].text. Use the n8n expression editor — it shows you the live structure when you have test data.

Different tools send different shapes

Here's the actual structure for the tools I use most:

Tally forms: Sends $json.body.data.fields — an array of field objects. Each has a label and value. You usually loop over them or find by label.

Stripe webhooks: $json.body.type tells you the event type (payment_intent.succeeded, customer.subscription.created, etc.). The data is at $json.body.data.object.

GitHub webhooks: $json.body.ref for the branch, $json.body.repository.full_name for the repo, $json.body.head_commit.message for the commit message.

Typeform: $json.body.form_response.hidden.email if you pass hidden fields. $json.body.form_response.answers array for actual responses.

Always use the Set node to clean your data early

I say this to everyone who asks me about workflow debugging: clean your data as the first thing after the webhook. Extract the fields you need, rename them to something human, and every downstream node becomes trivial to build.

Without this: {{ $json.body.form_response.answers[2].text }} — fragile, unreadable, breaks if answer order changes.

With a Set node: {{ $json.contact_email }} — obvious, clean, won't break if the form adds a question.

5 Real Webhook Use Cases (With Node Structures)

The 4 Mistakes I See Every Week in the n8n Community

I've replied to a lot of webhook debugging threads. Same four issues come up constantly:

1. Testing with the production URL. The production URL only works when the workflow is Active. The test URL only works while you're in the editor with "Listen for test event" active. Using the wrong one is responsible for roughly half the "my webhook isn't firing" posts. Check which URL you're using before posting for help.

2. Forgetting to respond to the webhook. By default, n8n keeps the HTTP connection open waiting to respond. If you have a long-running workflow (AI processing, multiple API calls), the sending service might time out. Add a "Respond to Webhook" node early in your flow (before the slow stuff) to immediately send {"status": "received"} and let the workflow continue asynchronously. This is especially important for Stripe and Twilio webhooks which require a fast response.

3. Not understanding synchronous vs asynchronous response. If your webhook needs to return data to the caller (like an AI agent responding to a query), you need to enable "Respond to Webhook" and set it to return the final output. This requires the workflow to complete before responding. Know which mode you need.

4. Hardcoding payload paths without test data. You guessed at what the payload structure looks like and hardcoded $json.body.data.email. The actual field is $json.body.email. Always fire a real test event first, look at the actual structure in the n8n node inspector, then build your expressions. Never guess.

What to Build Next

If you've followed this guide, you now have:

• A working webhook trigger that catches external events
• A Set node that cleans your data
• Downstream notifications (Telegram, Slack, email, Sheets)

The next natural step is stacking more logic on top. Some directions:

Add an IF node to route different payloads differently. New customer vs returning customer → different welcome emails. Urgent lead vs low-priority → different notification channels.

Add AI processing. Webhook catches an email forwarded via Zapier → AI node classifies it → responds differently based on category. The webhook is the input, AI is the brain, some action is the output.

Build a webhook-based API. Your n8n instance can literally act as a custom API server. Other tools send data to your webhook, your workflow processes it, the Respond to Webhook node sends back structured JSON. I use this for my Telegram bot — it sends messages to a webhook, my n8n workflow figures out what to do, responds with a formatted reply.

Webhooks are the first skill. Everything else in n8n automation stacks on top of them. Once you can receive external events and react to them, you're building real systems — not just scheduled cron jobs.

If you want the workflow JSON for the lead capture setup (plus 13 others from my production stack), I packaged them all up: