Introduction
This webhook relay setup guide explains what WebhookRelay is, how to install and authenticate the CLI, how relays and buckets work, and how to connect webhooks to localhost or a staging environment. It also covers custom domains, DNS, SSL/TLS, troubleshooting, and how WebhookRelay compares with ngrok and localtunnel.
WebhookRelay is useful when you need a stable webhook URL or callback URL for development, testing, or production workflows, but your app is not publicly exposed. Instead of pointing a provider directly at your local machine, you route the request flow through WebhookRelay and forward the payload to your endpoint.
If you want a refresher on the basics first, read what is a webhook, then continue with the WebhookRelay developer guide and the learn hub.
What is WebhookRelay?
A webhook is an HTTP callback: one service sends a request to your endpoint when an event happens. WebhookRelay is a developer tooling service that receives those webhook requests, routes them through a relay, and forwards them to the destination you choose.
That makes it useful for local testing, staging environments, and production environments where you need controlled webhook delivery without exposing internal services directly to the internet. You can use it to connect a webhook to localhost, route traffic to a reverse proxy, or create a custom domain for a cleaner public webhook URL.
WebhookRelay organizes traffic with relays and buckets. A relay defines the forwarding path for a webhook stream, while a bucket groups related webhook traffic so you can separate sources, environments, or event types. This structure helps with authentication, verification, and repeatable webhook testing.
How do I set up WebhookRelay step by step?
- Create a WebhookRelay account and sign in.
- Install the CLI on macOS, Linux, or Windows.
- Authenticate the CLI with an API key.
- Create a relay and, if needed, a bucket.
- Point the relay to your local server, staging endpoint, or production endpoint.
- Send a test webhook and confirm delivery.
That is the basic request flow: source service -> WebhookRelay webhook URL -> your callback URL or endpoint.
How do I install the WebhookRelay CLI?
Install the CLI using the official instructions for your operating system. On macOS, Linux, and Windows, WebhookRelay typically provides package-manager or binary-based installation options. After installation, verify the CLI is available by running the help or version command shown in the docs.
If the command is not found, check your PATH, reopen your terminal, and confirm the installation completed successfully. If you are using a config file for CLI settings, make sure it is in the expected location and readable by your user account.
How do I authenticate WebhookRelay with an API key?
Authenticate the CLI with an API key so it can create and manage relays and buckets on your account. A common approach is to store the key in an environment variable such as WEBHOOKRELAY_APIKEY, then run the authentication command described in the official documentation.
Best practices:
- Keep the API key out of source control.
- Use environment variables for local development.
- Use a config file only if your team’s workflow requires it.
- Rotate the key if you suspect it has been exposed.
If authentication fails, confirm the API key is active, copied correctly, and associated with the right account.
What are relays and buckets in WebhookRelay?
A relay is the routing rule that receives a webhook and forwards it to a destination endpoint. A bucket is a grouping layer that helps you organize multiple webhook streams, such as separate sources for development, staging, and production.
Use a relay when you only need one forwarding path. Use a bucket when you want to separate payloads, manage multiple endpoints, or keep webhook verification and retry behavior easier to track.
How do I connect a webhook to localhost?
To connect a webhook to localhost, create a relay that points to your local service, such as http://localhost:3000/webhook. Then configure the external service to send its webhook URL to the WebhookRelay address instead of your machine directly.
This is especially useful for local testing because you can inspect the payload immediately, verify headers and authentication, and confirm the endpoint responds correctly without opening inbound ports on your computer.
If your local app is behind a reverse proxy, point the relay at the proxy’s local address instead of the app process directly.
How do I create a custom webhook domain?
To create a custom webhook domain, choose a subdomain such as webhooks.example.com, then add a CNAME record in your DNS provider that points to the WebhookRelay target. After that, wait for DNS propagation and complete the domain verification step in WebhookRelay.
Do I need DNS access to use a custom domain? Yes. You need DNS access to create and update the CNAME record. You do not need DNS access for a basic setup that uses the default WebhookRelay URL.
If DNS propagation is slow, check the record value, TTL, and whether your DNS provider has fully published the change. If verification still fails, recheck the CNAME target and confirm the domain is assigned to the correct relay or bucket.
How does WebhookRelay handle SSL/TLS?
WebhookRelay uses HTTPS with SSL/TLS so webhook payloads are encrypted in transit. In a custom domain setup, certificate provisioning is handled as part of the domain configuration flow, which reduces the manual work required to secure the webhook URL.
For production environments, confirm that the certificate is active before switching the source service to the new callback URL. If you are testing in staging, verify that HTTPS is enabled end to end and that the endpoint accepts the forwarded request.
How do I test my first webhook after setup?
After setup, send a test webhook from the source service or use the provider’s webhook testing tools. Confirm that the request reaches WebhookRelay, that the payload is forwarded, and that your endpoint returns a successful response.
Check:
- Relay logs for the incoming request
- Endpoint logs for the forwarded request
- Response status codes
- Authentication or verification errors
- Timeout behavior if the endpoint is slow
If the test fails, retry after fixing the endpoint URL, confirming the service is running, and checking whether the source provider expects a verification response.
What should I do if webhook delivery fails?
If webhook delivery fails, start with the request flow and isolate where it breaks:
- Confirm the source service is sending to the correct webhook URL.
- Check whether WebhookRelay received the payload.
- Verify the callback URL or endpoint is reachable.
- Review authentication and verification settings.
- Look for timeout errors or 5xx responses.
- Check whether retries are enabled and whether the failure is temporary.
If the issue involves DNS, recheck the CNAME record and wait for DNS propagation to complete. If the issue involves SSL/TLS, confirm the certificate is provisioned and the HTTPS endpoint is valid.
What are the best practices for webhook relay configuration?
Use separate relays for development, staging, and production environments. Keep relay names descriptive, store secrets in environment variables, and document which webhook URL maps to which callback URL.
Other best practices:
- Use buckets to separate event types or services.
- Test every endpoint before promoting it to production.
- Monitor retries and timeouts.
- Prefer HTTPS for all public webhook URLs.
- Keep a config file under version control only if it does not contain secrets.
- Revisit verification rules whenever the source provider changes its payload format.
WebhookRelay vs ngrok and localtunnel
WebhookRelay and ngrok both help you expose local services, but they are optimized for different workflows. ngrok is often the faster choice when you need a temporary tunnel to localhost for a quick demo or debugging session. WebhookRelay is better when you want a stable webhook relay setup guide outcome: repeatable routing, a persistent webhook URL, custom domains, and webhook-specific configuration that you can reuse across environments.
localtunnel is simpler and works well for short-lived local testing, but it is not as strong for managed routing, team workflows, or production handoff. A reverse proxy such as Nginx or Traefik is different again: it routes traffic inside infrastructure you already control, while WebhookRelay is designed to receive external webhooks and forward them into local, staging, or internal endpoints.
If you are choosing between tools, use WebhookRelay for developer tooling that needs reliable webhook testing, use ngrok for quick exposure of localhost, and use localtunnel when you only need a temporary public URL.
For more context, see the WebhookRelay for local testing guide and the webhook testing for developers article.