Webhook Development

Q: How do I test Stripe webhooks on localhost?

Run localport http 4000 --token tok_YOUR_TOKEN --region eu with the port your handler listens on, then add the tunnel URL and your webhook path as an endpoint in Stripe under Developers, then Webhooks. Events arrive at your local handler.

Summary

A webhook provider needs a public HTTPS URL, and your local server has none. An HTTP tunnel gives it one that stays the same across restarts, so you register it with the provider once. Fanout delivers each webhook to every teammate, and signature verification drops forged deliveries before they reach you.

How webhooks reach your machine#

The provider sends each event to your tunnel's public URL. Localport carries the request to the port your handler listens on and returns your handler's response to the provider. The agent connects outward, so nothing on your network accepts an inbound connection.

You need a Localport account, the Localport agent, and a webhook handler listening on a local port.

Start the tunnel#

1. Create an HTTP tunnel in the dashboard. HTTP Tunnels walks through the panel.

2. Run the command the dashboard gives you, with the port your handler listens on:

localport http 4000 --token tok_YOUR_TOKEN --region eu

3. Copy the public URL the agent prints. It has this form:

https://my-application.eu.localport.dev

The URL belongs to the tunnel and does not change when the agent restarts. Register it with a provider once and it keeps working the next day.

Start the tunnel before you save the URL

Some providers send a test request the moment you save an endpoint. Have the agent and your handler running first.

Register the URL with your provider#

Add the path your handler serves to the tunnel URL, and paste the result into the provider's webhook settings.

Provider	Where the endpoint is set	Example endpoint
Stripe	Developers, then Webhooks	`https://my-application.eu.localport.dev/webhooks/stripe`
GitHub	Repository settings, then Webhooks	`https://my-application.eu.localport.dev/webhooks/github`
Shopify	Settings, then Notifications	`https://my-application.eu.localport.dev/webhooks/shopify`
Slack	Your app, then Event Subscriptions	`https://my-application.eu.localport.dev/slack/events`

Slack verifies the URL when you enter it. It sends a challenge, and your handler has to answer with the challenge value before Slack accepts the endpoint.

For GitHub, choose application/json as the content type so the body your handler reads matches the body GitHub signed.

Verify signatures before your code runs#

A webhook URL is public, so anyone who learns it can post to it. Turn on Webhook Signature Verification and Localport checks the provider's signature on every delivery. A request with a missing or wrong signature is refused and never reaches your machine.

GitHub, Stripe, Shopify and Slack are built in. Any other provider that signs with HMAC-SHA256 works through the Custom option.

A provider usually accepts one endpoint, and a team has several developers. Switch the tunnel's delivery to Fanout and every connected teammate receives a copy of each webhook on their own machine.

localport http 4000 --token tok_YOUR_TOKEN --region eu

Every teammate runs the same command with the same token. One of them is the primary, and the provider receives the primary's response.

Frequently asked questions#

Does the webhook URL change when I restart the agent?

No. The URL belongs to the tunnel, so it is the same after every restart. Set your own subdomain in the tunnel's settings to choose the name.

How do I test Stripe webhooks on localhost?

Run localport http 4000 --token tok_YOUR_TOKEN --region eu with the port your handler listens on, then add the tunnel URL and your webhook path as an endpoint in Stripe under Developers, then Webhooks. Events arrive at your local handler.

Can several developers receive the same webhook?

Yes. Set the tunnel's delivery to Fanout and each connected teammate receives a copy of every request. The provider sees one response, from the primary. Fanout Tunnels explains how the primary is chosen.

Can Localport reject forged webhooks?

Yes. With signature verification on, a delivery whose signature does not match your signing secret is refused before it reaches your machine. Webhook Signature Verification lists the supported providers.

Why is my webhook not arriving?

Check that the agent is running and that the endpoint in the provider's settings is the tunnel URL plus your handler's path. Then open the provider's delivery log: it shows the response code your handler returned for each attempt.

Does Localport store webhook payloads?

No. A request is carried to your machine and its content is not logged or stored. Localport records counts, sizes and times.