Self-Host Convoy for Remote Webhooks with Localtonet

How Convoy and Localtonet fit together

A webhook is an HTTP request sent when an event occurs. The sender needs a network-reachable URL, while the receiving application needs to validate, process, and acknowledge the request. A webhook gateway adds a control layer between those two sides. Convoy can receive incoming webhooks from providers and route them to the required services. It can also support outgoing webhook delivery from internal applications to users.

Convoy documents capabilities including event persistence, event search, retries, rate limiting, filtering, payload transforms, fan-out delivery, circuit breaking, endpoint failure notifications, and payload signing. It includes server and agent components that can be scaled independently. The exact set of features available to a deployment can depend on the Convoy edition, license, release, and configuration, so this guide does not assume that every listed capability is enabled on every instance.

Localtonet solves a separate networking problem. The Localtonet client runs on the machine that can reach Convoy and establishes an outbound connection to one of our relay servers. An HTTP tunnel then maps a public HTTPS address to Convoy's local HTTP address and port. This does not install, configure, or replace Convoy. Convoy remains responsible for webhook ingestion, authentication options, routing, persistence, retries, and delivery behavior.

Expected request flow

In a typical incoming-webhook workflow, a provider sends an HTTPS request to the public URL assigned to the Localtonet HTTP tunnel. Our relay forwards the HTTP traffic through the outbound client connection to the configured local Convoy IP address and port. Convoy evaluates the request at the specified route, applies its configured authentication and processing rules, and then routes or delivers the event to the appropriate internal service.

Exposing only the intended webhook interface is preferable to treating the entire Convoy installation as a generally public administration service. Whether webhook ingestion and administration share one listener or can be separated depends on the selected Convoy deployment and configuration. Verify that distinction in the running release before deciding what to publish.

Prerequisites and deployment decisions

Convoy's project documentation identifies Docker and Kubernetes with Helm as supported installation paths. Its website also publishes a shell-based quick-install command. Those paths serve different operational needs, and they should not be mixed casually. Choose one deployment method, understand where its persistent data lives, and keep a record of the generated configuration.

This article uses the project's published shell command as the only exact Convoy installation command because it is the exact command present in the supplied official evidence. The evidence available for this draft does not establish the installer's supported operating systems, generated file paths, container names, default credentials, default hostname, default port, or complete dependency topology. We therefore do not invent those details. The installer's output and the configuration generated for your selected release are authoritative for the local address you will use later.

Host preparation checklist

• Use a dedicated or appropriately isolated host that you administer.
• Confirm that the host can reach the internet to download required installation artifacts.
• Install the prerequisites required by the selected official Convoy deployment path.
• Confirm that persistent application and database data will survive a restart or container replacement.
• Decide how configuration, credentials, signing secrets, and database credentials will be stored and backed up.
• Check that the Localtonet client can run on this host or on another device that can reach Convoy over the local network.
• Reserve the local listener address and port reported or configured by the Convoy deployment.
• Ensure that internal destination services are reachable from Convoy if it will route incoming events to those services.

Plan names and addresses before deployment

Record the host's local IP address, the Convoy HTTP bind address, and the published HTTP port as separate values. A service bound only to 127.0.0.1 is reachable from software on the same host but not directly from a different LAN device. That is suitable when the Localtonet client runs on the Convoy host. If the client runs elsewhere, Convoy must be reachable on a suitable LAN interface, and host firewall rules should allow only the required local source.

Avoid changing Convoy to listen broadly merely because remote access is needed. If the Localtonet client runs on the same machine, a loopback listener usually reduces LAN exposure. If containers are involved, remember that an application listener inside a container is not automatically the same as a port published on the host. Use the port mapping produced by the deployment rather than guessing from an internal container port.

Install Convoy using an official deployment path

Convoy's website publishes the following quick-start installation command:

curl -fsSL https://getconvoy.io/install | bash

Run it only after completing the security review described above. Preserve the full terminal output. The output is important because it may identify prerequisites, generated credentials, component status, management commands, configuration locations, or the address where the installed release is listening.

Docker-specific checks

For a Docker deployment, inspect the actual running containers and published ports rather than assuming a conventional port. The following generic Docker commands can help when Docker is the selected runtime:

docker ps
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

Identify the Convoy-related components created by the official deployment and confirm that they remain running. A port shown only as an internal container port is not necessarily reachable through the host. Look for the host-side mapping generated by your deployment. Use the deployment's own log command or Docker's standard logging command with the real container name displayed by docker ps. Do not copy a container name from an unrelated installation.

Kubernetes-specific checks

For Kubernetes, confirm that the Helm release completed, the required workloads became ready, and the intended service has endpoints. The exact namespace, release name, chart values, service names, and ports are deployment choices and are not established by the supplied evidence. Retrieve them from the Helm values and Kubernetes objects in your own cluster.

Decide whether the Localtonet client will run on a node, on a separate machine that can reach the Kubernetes service, or in another approved location. The target supplied to Localtonet must remain reachable from that client. Do not point an external client at a cluster-only DNS name unless that client actually participates in the cluster network.

Configure Convoy for incoming webhooks

A running Convoy process is only the foundation. Incoming webhook delivery also requires a configured project or equivalent logical scope, an incoming source or route, appropriate authentication, and a destination service or subscription behavior. Names and screen layouts can change between releases, so use the terminology displayed by the running version instead of relying on screenshots from another release.

Separate administration from ingestion

First determine which route external providers need. The public webhook URL should point to the specific incoming webhook route generated or configured by Convoy. It should not be assumed to be the dashboard root, a health endpoint, or a general API endpoint.

Administrative access deserves stronger restrictions than machine-to-machine ingestion. If the deployment allows separate listeners, hostnames, or routing controls, keep the administration surface private and expose only the webhook-facing interface. If they share a listener, use Convoy's access controls and any available routing restrictions to reduce what unauthenticated internet clients can use.

Configure authentication deliberately

Convoy documents bearer-token authentication for authenticated webhook endpoints, payload signing, OAuth2, and mutual TLS support for endpoints that require those mechanisms. These capabilities do not mean that every new incoming endpoint is automatically protected. Select the mechanism supported by the sending provider and verify how Convoy applies it in your release.

Keep provider secrets, bearer tokens, signing secrets, OAuth credentials, database passwords, and Localtonet device tokens out of shell history, public screenshots, source repositories, and article examples. Use your deployment's secret-management facility. If a provider signs requests, validate signatures according to that provider's algorithm and use the unmodified request body where its verification procedure requires it.

Configure routing and failure behavior

Convoy can route events based on event type or payload structure, fan an event out to multiple endpoints, filter requests using body, headers, query, or path data, and apply JavaScript transforms before delivery. Configure these features narrowly. A broad subscription may deliver data to more destinations than intended, while an incorrect filter can silently drop nonmatching events.

Configure retries with the receiving application's behavior in mind. Convoy supports constant-time retries and exponential backoff with jitter, as well as batch retries for endpoints that continue to fail. Retryable delivery means the destination must be prepared for duplicate attempts. Use stable event identifiers or idempotency keys when available, and design handlers so repeated delivery does not repeat irreversible business actions.

Rate limits and circuit breaking should reflect the capacity of downstream services. Convoy can throttle delivery per endpoint and open a circuit after consecutive failures. Endpoint failure notifications can be delivered through supported notification channels when configured. Test these controls with nonproduction data before relying on them during an incident.

Verify Convoy locally before creating a tunnel

Remote testing should begin only after local verification succeeds. This isolates Convoy deployment errors from tunnel configuration errors and gives you a known-good local target.

Once you know the verified local base address, save it in a form such as LOCAL_IP:LOCAL_PORT. Replace those labels with your real values only in your private configuration. If Convoy and the Localtonet client run on the same host, the local IP may be a loopback address if the deployment listens there. If the client runs on another machine, use an address reachable from that machine.

Interpret HTTP results correctly

Expose the verified Convoy HTTP service with Localtonet

The Localtonet integration begins only after the Convoy target is known to work locally. Install and run our client on the Convoy host or on a device that can reach Convoy's verified local address. The client establishes an outbound connection, so the workflow does not require inbound router port forwarding, firewall changes at the internet edge, VPN setup, or a public IP address.

HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. These process types serve content at a public HTTPS address. Availability can vary by plan and current dashboard options. Exact custom-domain DNS instructions are not included here because they must be checked against the current configuration shown by our platform.

The complete current product workflow is also available in our HTTP tunnel documentation. Use the dashboard's current labels and values if they differ from an older interface.

Test end-to-end remote webhook delivery

Test in layers. Begin with a disposable Convoy route and non-sensitive data. A useful test proves more than public reachability: it proves that the request crosses the tunnel, reaches the correct Convoy route, passes authentication, is persisted or recorded as expected, matches the intended subscription, and reaches the downstream service.

1. Confirm that Convoy and its required dependencies are healthy.
2. Confirm that the Localtonet device is connected and the HTTP tunnel is running.
3. Build the remote URL from the assigned public base address and the exact Convoy incoming route.
4. Send the HTTP method, content type, authentication material, and body expected by that route.
5. Inspect the returned HTTP status without treating one successful response as a complete reliability test.
6. Find the event in Convoy by its identifier, type, source, or another available search field.
7. Confirm that the correct subscription matched and any configured filter or transform behaved as intended.
8. Verify delivery at the downstream application and compare its event identifier with Convoy's record.
9. Repeat the test with an invalid credential and confirm rejection.
10. Repeat with a duplicate event and confirm that the receiving workflow handles duplication safely.

Use a parameterized request instead of inventing a route

The following pattern intentionally contains placeholders because Convoy's public webhook path and authentication requirements come from your configured instance:

curl -i \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TEST_CREDENTIAL' \
  --data '{"event":"localtonet.convoy.test","test":true}' \
  'https://YOUR_PUBLIC_HOST/EXACT_CONVOY_WEBHOOK_PATH'

Replace the placeholders privately. Omit or change the authorization header if the Convoy route uses a different documented mechanism. Never send a real credential in a shared terminal recording, ticket, chat message, or public command example.

A webhook sender may consider any non-success response a failed attempt and retry it. Return behavior is controlled by Convoy and the route configuration, while delivery behavior can continue after ingestion. Observe both the immediate response to the sender and the later destination result.

Test failure paths before production

Temporarily direct a test subscription to a controlled endpoint that returns an error, or stop a disposable receiving service. Confirm that the selected retry policy behaves as expected and that the receiver can tolerate repeated requests. If circuit breaking is configured, verify its transition and recovery behavior. Restore the endpoint and confirm that delivery resumes according to the configured policy.

Also test a request that should not match a filter. Convoy documents that nonmatching events are dropped when filters apply. Ensure this is the intended outcome and that the filter does not discard a legitimate provider variant. Test transforms with representative payloads, including missing optional fields and unexpected additional fields.

Operate the gateway safely

Back up state and configuration

Document the persistent storage created by the selected deployment and include it in a tested backup plan. Configuration alone may not preserve event history, endpoint state, retry state, users, projects, or other database-backed information. The exact backup and restoration commands depend on the official deployment and database arrangement, which are not established by the supplied evidence.

Test restoration on an isolated system. A backup that has never been restored is not a verified recovery process. Protect backups because webhook payloads and endpoint configuration may contain sensitive business data.

Monitor both service layers

Monitor Convoy's application components, dependencies, queue behavior, destination failures, and available storage. Separately monitor the Localtonet device and tunnel state. Our platform provides Token and Tunnel webhooks that can report Connected and Disconnected changes for a selected Token Group. Those platform lifecycle notifications are not Convoy event notifications and are not file-level webhooks.

A public endpoint check can detect whether the overall path responds, but avoid probes that generate real business events. Use a dedicated health route only if the selected Convoy release documents one and its exposure is appropriate. This article does not invent a health-check path.

Plan upgrades deliberately

Pin and record the Convoy release used by your deployment according to its official installation method. Before upgrading, review release notes, confirm database migration requirements, back up persistent data, and test the new version with representative incoming and outgoing events. Preserve a rollback plan compatible with any schema changes.

After an upgrade, repeat local and public verification. Confirm authentication, filters, transforms, retries, dashboard access, and downstream delivery rather than checking only that the process started.

Rotate and revoke credentials

Maintain an inventory of provider credentials, Convoy secrets, signing keys, downstream credentials, administrative accounts, and Localtonet device tokens. Rotate them according to your security policy and immediately after suspected disclosure. Update one side at a time where rolling-secret support or provider overlap allows a controlled transition.

Stop the Localtonet tunnel when public ingestion is not needed. Delete obsolete tunnels and remove unused Convoy endpoints. Stopping a tunnel makes its public path unavailable while preserving the local Convoy deployment. Deleting the Convoy endpoint and deleting the Localtonet tunnel are separate actions.

Troubleshooting Convoy and Localtonet

The public URL does not connect

Confirm that the Localtonet client is running and its device is connected. Then confirm that the tunnel has been started. Creation alone is not enough. Verify that the configured local IP and port exactly match the values that passed local testing.

From the Localtonet client device, request the local Convoy address directly. If that fails, the problem is between the client and Convoy rather than at the public URL. Check bind addresses, container port publishing, Kubernetes network scope, local routing, and host firewall policy.

The public root works but webhooks fail

This usually indicates a route-level issue. Check the complete URL supplied to the sender, including the exact Convoy webhook path. Confirm the HTTP method, content type, required headers, bearer token or other authentication mechanism, and body format. A dashboard response at the root does not prove that an incoming webhook route exists.

Convoy records the event but the destination receives nothing

Inspect subscription matching, filters, transformations, endpoint status, destination URL, destination authentication, rate limits, retry state, and circuit-breaker state. Test the destination directly from the Convoy network context. If Convoy runs inside a container or cluster, a destination such as 127.0.0.1 refers to that container or pod context, not automatically to another host service.

The provider reports timeouts or duplicate deliveries

Compare timestamps in the provider, Localtonet-facing request test, Convoy event record, and destination logs. A provider may retry after a timeout even if the original request eventually entered the system. Make the downstream handler idempotent and correlate requests using stable event identifiers when available.

Avoid raising timeouts or disabling retries without understanding the failure. Check database health, queue processing, downstream latency, resource pressure, DNS resolution, and destination response times.

Authentication works locally but fails remotely

Compare the exact request sent in each test. Check whether the provider follows redirects, changes the host header, encodes the body differently, or omits an expected header. For signature verification, even a small change to the raw body can invalidate the signature. Use the sender's documented signing procedure and Convoy's matching verification configuration.

The tunnel disconnects intermittently

Confirm that the Localtonet client process is supervised and that the host is not sleeping, restarting, or losing outbound connectivity. Check the selected device and tunnel state separately. If Convoy remains locally reachable during the incident, focus on client connectivity and tunnel lifecycle. If Convoy also fails locally, investigate the host and Convoy deployment first.

Frequently asked questions