Webhook development guide
Test webhooks on localhost with a public HTTPS URL
Receive webhook callbacks on localhost, inspect request metadata, and protect development endpoints with a Proxlane HTTP tunnel.
Example target
127.0.0.1:3000
Callback URL
Public HTTPS
Useful for
OAuth and webhooks
Publish step by step
- 01
Run the webhook handler
Start the application and verify the callback path locally, for example http://127.0.0.1:3000/webhooks/example.
- 02
Start an HTTP tunnel
Use the Web app card in Launcher or publish the port with the CLI.
proxlane http 3000 - 03
Configure the external callback
Copy the public HTTPS URL and append the same path, such as /webhooks/example. Save that complete URL in the provider's development webhook settings.
- 04
Send a test event and inspect it
Trigger a provider test event, then check the local application and Proxlane Logs. Keep signature verification enabled in your application when the provider supports it.
Keep callback URLs stable when needed
Random hostnames can change after a restart. For OAuth redirect URIs or providers that require a pre-registered callback, reserve a stable Proxlane hostname or use a verified custom domain on a compatible plan.
Inspect metadata without exposing secrets
Proxlane records operational request metadata for troubleshooting. Authorization, Cookie, and other sensitive values are redacted. Application-level webhook signatures should still be verified by your handler.
Restrict a development callback
Use relay-side protection when the sender supports authentication or stable source addresses. Do not add Basic Auth in front of a provider that cannot send those credentials; rely on the provider's signed payload instead.
Troubleshooting
Provider reports a timeout
Confirm the local handler returns promptly. A webhook provider may stop waiting before a long local job completes, so enqueue work and return a successful response first.
404 from the public URL
The tunnel only changes the host. Make sure the public callback includes the same path and HTTP method that your local application expects.
Signature verification fails
Use the original request body when computing the signature. Parsing and serializing JSON before verification can change the signed bytes.
Frequently asked questions
Can I use the URL for an OAuth callback?
Yes, if the provider accepts the public HTTPS URL. Use a reserved hostname when the redirect URI must remain registered across restarts.
Does Proxlane replace webhook signature checks?
No. Tunnel protection reduces exposure, but the receiving application should still verify provider signatures and reject replayed or invalid events.
Proxlane