Setting Up Webhooks for Local Development

When developing applications that use webhooks, you’ll need a publicly accessible URL that ContactManager can reach. This is a challenge when developing locally, as your development server typically doesn’t have a public URL.

Why Localhost Doesn’t Work

Webhooks can only send data to publicly accessible URLs. When you’re developing locally:

Your machine doesn’t have a public URL that our servers can reach
Local addresses (localhost, 127.0.0.1) are blocked for security reasons
Private network addresses (192.168.x.x) are not reachable from the internet

Using Tunneling Services

The solution is to use a secure tunneling service that creates a public URL for your local development server. The most popular options are:

ngrok is a widely used tunneling service that’s perfect for webhook development.

Setup Steps

Install ngrok

# macOS (using Homebrew)
brew install ngrok

# Windows (using Chocolatey)
choco install ngrok

# Using npm
npm install -g ngrok

Start your local server Start your application server on a local port (e.g., port 3000)
Create a tunnel with ngrok
```
ngrok http 3000
```
Use the provided URL ngrok will display a URL (e.g., https://abc123.ngrok.io). Use this as your webhook URL in the ContactManager dashboard.

Example Output

Session Status                online
Account                       yourname@example.com
Version                       3.3.1
Region                        United States (us)
Latency                       51ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Benefits

Free tier available
Simple setup
Web interface for inspecting requests
Supports custom domains (paid plans)

ngrok is a widely used tunneling service that’s perfect for webhook development.

Setup Steps

Install ngrok

# macOS (using Homebrew)
brew install ngrok

# Windows (using Chocolatey)
choco install ngrok

# Using npm
npm install -g ngrok

Start your local server Start your application server on a local port (e.g., port 3000)
Create a tunnel with ngrok
```
ngrok http 3000
```
Use the provided URL ngrok will display a URL (e.g., https://abc123.ngrok.io). Use this as your webhook URL in the ContactManager dashboard.

Example Output

Session Status                online
Account                       yourname@example.com
Version                       3.3.1
Region                        United States (us)
Latency                       51ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Benefits

Free tier available
Simple setup
Web interface for inspecting requests
Supports custom domains (paid plans)

Cloudflare Tunnel provides a secure way to connect your local development environment to the internet.

Setup Steps

Install cloudflared

# macOS (using Homebrew)
brew install cloudflare/cloudflare/cloudflared

# Windows (using Scoop)
scoop install cloudflared

Start a quick tunnel

cloudflared tunnel --url http://localhost:3000

Use the provided URL Cloudflare will generate a URL (e.g., https://random-words.trycloudflare.com). Use this as your webhook URL.

Benefits

Free to use
Backed by Cloudflare’s global network
No time limitations
Option to create persistent tunnels

localtunnel is a simple, open-source alternative.

Setup Steps

Install localtunnel
```
npm install -g localtunnel
```
Start your local server Start your application server on a local port (e.g., port 3000)
Create a tunnel
```
lt --port 3000
```
Use the provided URL localtunnel will display a URL (e.g., https://abcd1234.loca.lt). Use this as your webhook URL.

Benefits

Completely free and open-source
Minimal setup
Supports custom subdomains

Verifying Webhook Requests Locally

When developing locally, you’ll want to examine the webhook payloads for debugging:

ngrok provides a built-in inspector that shows all HTTP traffic:

Start ngrok as usual
Open http://localhost:4040 in your browser
View all incoming webhook requests in real-time
Inspect headers, body, and other details

This is a powerful debugging tool that lets you see exactly what ContactManager is sending.

ngrok provides a built-in inspector that shows all HTTP traffic:

Start ngrok as usual
Open http://localhost:4040 in your browser
View all incoming webhook requests in real-time
Inspect headers, body, and other details

This is a powerful debugging tool that lets you see exactly what ContactManager is sending.

Add detailed logging to your webhook handler:

app.post('/webhooks/contactsmanager', (req, res) => {
  // Log the request for debugging
  console.log('Webhook received:');
  console.log('Headers:', req.headers);
  console.log('Body:', JSON.stringify(req.body, null, 2));

  // Rest of your handler code...
});

This approach works with any tunneling service and gives you a record of each webhook received.

Testing Webhook Flows

To fully test your webhook implementation during development:

Use the dashboard test tool The ContactManager dashboard provides a test tool to send sample webhook events to your endpoint.
Trigger real events Perform actions in your test environment (like creating a user or following someone) to trigger real webhook events.
Check webhook logs In the ContactManager dashboard, you can view detailed logs of webhook deliveries, including response codes and timing.

Webhook Security in Development

Even during development, it’s important to implement proper webhook verification:

// Always verify webhook signatures, even in development
if (!verifyWebhookSignature(req.body, signature)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

This ensures your production and development codepaths are identical, preventing security issues when you deploy.

Troubleshooting

Problem	Solution
Webhook URL is rejected	Ensure you’re using HTTPS and a public domain (not localhost or IP address)
Signature verification fails	Double-check your webhook secret and ensure you’re using the correct verification code
Webhook is not received	Check your tunnel is running and verify the URL in the dashboard matches your tunnel URL
Webhook times out	Ensure your local server responds within the timeout period (30 seconds)

Get Started

Features

Services

Webhooks

Models

Local development

Setting Up Webhooks for Local Development

Why Localhost Doesn’t Work

Using Tunneling Services

Setup Steps

Example Output

Benefits

Setup Steps

Example Output

Benefits

Setup Steps

Benefits

Setup Steps

Benefits

Verifying Webhook Requests Locally

Testing Webhook Flows

Webhook Security in Development

Troubleshooting

Next Steps

Get Started

Features

Services

Webhooks

Models

​Setting Up Webhooks for Local Development

​Why Localhost Doesn’t Work

​Using Tunneling Services

​Setup Steps

​Example Output

​Benefits

​Setup Steps

​Example Output

​Benefits

​Setup Steps

​Benefits

​Setup Steps

​Benefits

​Verifying Webhook Requests Locally

​Testing Webhook Flows

​Webhook Security in Development

​Troubleshooting

​Next Steps

Setting Up Webhooks for Local Development

Why Localhost Doesn’t Work

Using Tunneling Services

Setup Steps

Example Output

Benefits

Setup Steps

Example Output

Benefits

Setup Steps

Benefits

Setup Steps

Benefits

Verifying Webhook Requests Locally

Testing Webhook Flows

Webhook Security in Development

Troubleshooting

Next Steps