​
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

  1. Install ngrok 
    # macOS (using Homebrew)
brew install ngrok

# Windows (using Chocolatey)
choco install ngrok

# Using npm
npm install -g ngrok
  2. Start your local server Start your application server on a local port (e.g., port 3000)
  3. Create a tunnel with ngrok 
    ngrok http 3000
  4. 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)

​
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:
  1. Start ngrok as usual
  2. Open http://localhost:4040 in your browser
  3. View all incoming webhook requests in real-time
  4. Inspect headers, body, and other details
This is a powerful debugging tool that lets you see exactly what ContactManager is sending.

​
Testing Webhook Flows

To fully test your webhook implementation during development:
  1. Use the dashboard test tool The ContactManager dashboard provides a test tool to send sample webhook events to your endpoint.
  2. Trigger real events Perform actions in your test environment (like creating a user or following someone) to trigger real webhook events.
  3. 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

ProblemSolution
Webhook URL is rejectedEnsure you’re using HTTPS and a public domain (not localhost or IP address)
Signature verification failsDouble-check your webhook secret and ensure you’re using the correct verification code
Webhook is not receivedCheck your tunnel is running and verify the URL in the dashboard matches your tunnel URL
Webhook times outEnsure your local server responds within the timeout period (30 seconds)

​
Next Steps