> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactsmanager.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Webhook Development

> Guide to setting up and testing ContactManager webhooks in a local development environment using tunneling services and debugging tools

# 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:

<Tabs>
  <Tab title="ngrok">
    [ngrok](https://ngrok.com/) is a widely used tunneling service that's perfect for webhook development.

    ### Setup Steps

    1. **Install ngrok**
       ```bash theme={null}
       # 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**
       ```bash theme={null}
       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)
  </Tab>

  <Tab title="Cloudflare Tunnel">
    [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) provides a secure way to connect your local development environment to the internet.

    ### Setup Steps

    1. **Install cloudflared**
       ```bash theme={null}
       # macOS (using Homebrew)
       brew install cloudflare/cloudflare/cloudflared

       # Windows (using Scoop)
       scoop install cloudflared
       ```

    2. **Start a quick tunnel**
       ```bash theme={null}
       cloudflared tunnel --url http://localhost:3000
       ```

    3. **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
  </Tab>

  <Tab title="localtunnel">
    [localtunnel](https://localtunnel.github.io/www/) is a simple, open-source alternative.

    ### Setup Steps

    1. **Install localtunnel**
       ```bash theme={null}
       npm install -g localtunnel
       ```

    2. **Start your local server**
       Start your application server on a local port (e.g., port 3000)

    3. **Create a tunnel**
       ```bash theme={null}
       lt --port 3000
       ```

    4. **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
  </Tab>
</Tabs>

## Verifying Webhook Requests Locally

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

<Tabs>
  <Tab title="ngrok Inspector">
    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.
  </Tab>

  <Tab title="Request Logging">
    Add detailed logging to your webhook handler:

    ```javascript theme={null}
    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.
  </Tab>
</Tabs>

## 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:

```javascript theme={null}
// 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)                 |

## Next Steps

* [Return to implementation guide](/webhooks/implementation)
* [Learn about webhook security](/webhooks/security)