Local Webhook Proxy Guide

Test webhooks on localhost without ngrok or tunnels. Forward webhooks directly to your development server with Payloadr CLI.

Get Started Free

What is a Local Webhook Proxy?

A local webhook proxy allows you to receive webhooks from third-party services directly on your localhost development server.

Traditionally, testing webhooks locally requires exposing your machine to the internet using tools like ngrok. This approach has downsides:

Security risks from exposing localhost to the internet
Complex setup with port forwarding and tunnels
Doesn't work behind corporate firewalls
Unreliable connections that drop frequently

Payloadr's local webhook proxy solves these problems by establishing an outbound connection from your machine to our servers. When a webhook arrives, we forward it to your local development server instantly.

Installation & Setup

Step 1: Install Payloadr CLI

Install the CLI globally using npm:

$ npm install -g @payloadr/cli

Step 2: Create an Endpoint

Your endpoint URL:

https://payloadr.dev/your-user-id/my-endpoint

Step 3: Start the Proxy

Run the proxy command with your endpoint slug:

$ payloadr proxy my-endpoint

ℹ Payloadr CLI v1.0.0
✔ Authenticated as you@example.com
✔ Listening for webhooks on https://payloadr.dev/your-user-id/my-endpoint
✔ Proxying to http://localhost:3000/api/webhooks

Waiting for webhooks...

Step 4: Configure Your Webhook Source

Add your Payloadr endpoint URL to your third-party service (Stripe, GitHub, etc.). Webhooks will now be forwarded to your localhost automatically.

Advanced Usage

Custom Target Port and Path

Proxy to a different port or path:

$ payloadr proxy my-endpoint --target http://localhost:8080/webhooks

Verbose Logging

See detailed request and response information:

$ payloadr proxy my-endpoint --verbose

Multiple Endpoints

Run multiple proxy sessions in different terminals to forward different endpoints to different local services:

# Terminal 1
$ payloadr proxy stripe-webhooks --target localhost:3000

# Terminal 2
$ payloadr proxy github-webhooks --target localhost:4000

Example: Testing Stripe Webhooks Locally

Here's a complete example of testing Stripe webhooks on localhost:

1. Create endpoint in Payloadr:

Name: stripe-webhooks

2. Start the proxy:

$ payloadr proxy stripe-webhooks --target localhost:3000/api/stripe/webhook

3. Add webhook URL to Stripe Dashboard:

https://payloadr.dev/your-user-id/stripe-webhooks

4. Test with a Stripe event:

POST /api/stripe/webhook 200 OK
Event: payment_intent.succeeded
Amount: $29.00 USD

Frequently Asked Questions

Start Testing Webhooks Locally

Join developers using Payloadr to test webhooks on localhost. Simple setup, no tunnels required.

Get Started Free View All Features