DEV Community

lucas-brdt268
lucas-brdt268

Posted on

Building a Webhook Listener with Node.js (Step-by-Step Guide)

#backend #tutorial #javascript #node

Webhooks power modern integrations — whether it’s receiving payment notifications from Stripe, alerts from GitHub, or messages from Slack. Instead of constantly polling an API, you let the service push events to your app in real time.

In this post, we’ll build a simple webhook listener using Node.js + Express. By the end, you’ll know how to:

  • Understand what a webhook is
  • Set up a webhook endpoint in Node.js
  • Parse and log incoming events
  • Test your webhook locally with Ngrok

🧩 What is a Webhook?

A webhook is just an HTTP callback.

  • A service sends an HTTP request (usually POST) to your app when something happens.
  • Your app receives that request, processes it, and responds.

Example:

  • GitHub → sends a POST /webhook with info about a new pull request
  • Your app → logs the event or triggers another process

⚡ Step 1. Setup Project 

mkdir node-webhook-listener
cd node-webhook-listener
npm init -y
npm install express body-parser
Enter fullscreen mode Exit fullscreen mode

⚡ Step 2. Create Express Server

Create a file: index.js

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware to parse JSON
app.use(bodyParser.json());

// Webhook endpoint
app.post('/webhook', (req, res) => {
  console.log('📩 Webhook received:', req.body);

  // Always reply with 200 OK so the sender knows you got it
  res.status(200).send('Webhook received');
});

app.listen(PORT, () => {
  console.log(`🚀 Server is running on http://localhost:${PORT}`);
});
Enter fullscreen mode Exit fullscreen mode

Run it:

node index.js
Enter fullscreen mode Exit fullscreen mode

⚡ Step 3. Test Locally with Ngrok

External services can’t reach localhost, so we need to expose it with Ngrok.

npx ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

Ngrok will give you a public URL, like:

https://abc123.ngrok.io
Enter fullscreen mode Exit fullscreen mode

Now, if you send a webhook to:

https://abc123.ngrok.io/webhook
Enter fullscreen mode Exit fullscreen mode

It will forward it to your local server. 🎉

⚡ Step 4. Send a Test Request

You can simulate an external webhook using curl:

curl -X POST https://abc123.ngrok.io/webhook \
  -H "Content-Type: application/json" \
  -d '{"event":"order.created","data":{"id":123,"amount":500}}'
Enter fullscreen mode Exit fullscreen mode

Check your terminal — you should see:

📩 Webhook received: { event: 'order.created', data: { id: 123, amount: 500 } }
Enter fullscreen mode Exit fullscreen mode

🛡️ (Optional) Step 5. Secure Your Webhook

Most services sign webhook payloads with a secret. You should:

  • Verify the signature (HMAC)
  • Only accept requests from trusted sources
  • Avoid logging sensitive data

(We’ll dive deeper into webhook security in another post 👀)

🎯 Wrap Up

We just built a basic webhook listener in Node.js:

✅ Express server with /webhook endpoint
✅ Logging incoming events
✅ Local testing with Ngrok
✅ Ready to integrate with APIs like Stripe, GitHub, or Slack

Next steps:

  • Add signature verification
  • Connect the webhook events to your app’s logic
  • Deploy to a cloud service

👉 What services are you planning to integrate with webhooks? Let me know in the comments!

Top comments (0)