Run a self-hosted webhook delivery service locally, verify the deployment, and make its API reachable when remote access is required
Svix is an open-source webhook service that applications can use to manage and deliver outgoing webhooks. In this guide, we install the Svix server with its documented Docker Compose workflow, explain its PostgreSQL and Redis dependencies, review the standalone container alternative, and identify what can safely be verified without inventing an API request. After the server works locally, we connect its HTTP listener to a Localtonet tunnel so authorized remote applications can reach it without inbound router port forwarding, firewall changes, a VPN, or a public IP address.
📋 What's in this guide
What this Svix and Localtonet architecture does
Webhooks let one application notify another application when an event occurs. Although sending an HTTP request sounds simple, a production webhook system usually needs to track destinations, retry failed deliveries, provide delivery visibility, separate customer configurations, and handle security-sensitive data. Svix packages those responsibilities behind an API so an application can submit messages while the webhook service manages the delivery workflow.
This tutorial focuses on the open-source Svix server. The server is written in Rust, but the easiest documented installation path does not require compiling Rust code. Instead, the Svix repository provides a Docker Compose configuration that starts the server and configures the supporting PostgreSQL and Redis services. PostgreSQL stores events. Redis can provide the task queue and cache, although the Svix documentation identifies Redis as an optional runtime dependency depending on the selected configuration.
Local installation and public access are separate stages. First, we need a healthy Svix deployment that is usable from the Docker host or its local network. Only then should we create an HTTP tunnel. With Localtonet, our client application establishes an outbound connection from the host to a Localtonet relay server. The tunnel receives a public address and forwards HTTP traffic to the selected local IP address and port.
This design does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel remains available only while the selected Localtonet client is connected and the tunnel is running. Stopping the tunnel removes that remote access path without requiring Svix itself to be uninstalled.
Request path from a remote application
After setup, a remote application sends an HTTPS request to the public address assigned to the Localtonet HTTP tunnel. The Localtonet relay accepts that connection and passes the request through the active outbound client connection to the configured local target. The target is the IP address and published port through which the Docker host exposes Svix.
The public URL is therefore not a second Svix installation. It is a route to the local server. Database access and Redis access should remain internal to the Docker deployment. There is no reason to expose PostgreSQL or Redis merely because the Svix HTTP API needs to be reachable remotely.
A Localtonet tunnel can forward traffic to a local listener, but it cannot repair an unhealthy container, create a missing database schema, or supply an absent Svix configuration. Confirm that Docker reports the expected services as running and complete an authenticated Svix API operation locally before testing the public address.
Prerequisites for installing Svix with Docker
The documented Compose installation assumes that Docker and Docker Compose v2 are already available on the host. Docker Compose v2 uses the command form docker compose. Confirm that this command is available before starting the Svix stack.
You also need a local copy of the official svix-webhooks repository. Obtain that repository using your normal Git checkout or archive-download workflow. This guide does not prescribe an operating-system-specific package manager or repository path because those details vary by platform and are not established by the supplied Svix installation evidence.
Choose a host with enough resources for three services: the Svix server, PostgreSQL, and Redis. The verified material does not publish a universal CPU, memory, or storage minimum for this workflow, so we will not invent one. Actual requirements depend on event volume, payload size, retention, concurrent delivery activity, and the surrounding Docker environment.
| Requirement | Why it is needed | What to confirm |
|---|---|---|
| Docker Engine | Runs the Svix server and its supporting containers | The Docker service is installed, running, and usable by your account |
| Docker Compose v2 | Starts the supplied multi-container stack | The docker compose command is available |
| Svix repository checkout | Contains the documented server directory and Compose file |
You can enter the repository's server directory |
| Persistent local storage | PostgreSQL stores events, and Redis persistence is recommended for queued tasks | The Docker host has suitable storage and an appropriate backup plan |
| Localtonet client | Creates the outbound connection used by the HTTP tunnel | Install it only on a device that can reach the published Svix listener |
| Svix API credentials | Authenticated API requests require valid application credentials | Store credentials privately and never place them in a public URL or article example |
Decide where the Localtonet client will run
The simplest layout is to run the Localtonet client on the same machine that publishes the Svix container port. A different machine can also act as the tunnel client if it can reach that host over the local network. In that case, the tunnel target must use an address reachable from the client device rather than assuming that 127.0.0.1 refers to the Docker host.
Remember that loopback addresses are local to the process environment using them. If the Localtonet client runs directly on the Docker host, a host-published container port may be reachable through the host loopback address. If our client runs elsewhere, the target normally needs the Docker host's reachable LAN address and the published host port.
This workflow exposes the Svix HTTP service, not PostgreSQL and not Redis. Keep supporting data services private to the Docker network or another appropriately restricted internal network. Exposing them creates unnecessary attack surface and is not required for remote use of the Svix API.
Install Svix using Docker Compose
Docker Compose is the easiest installation method documented by the Svix project because the supplied configuration also starts and configures PostgreSQL and Redis. This avoids having to construct database connection strings, Redis settings, container networking, and all required environment values manually.
Obtain the official Svix repository
Download or clone the official svix-webhooks repository onto the Docker host. Keep the repository structure intact because the documented Compose workflow is run from its server directory.
Enter the server directory
Open a terminal in the repository root and change into the directory containing the server's Docker Compose configuration.
Start the Compose stack
Run the documented Docker Compose command. Docker Compose starts the Svix server along with the PostgreSQL and Redis services defined by the supplied project configuration.
cd server
docker compose upRunning the command without a detached-mode option keeps Compose attached to the terminal and displays container output. This is useful during the first startup because initialization failures, invalid settings, dependency connection errors, and container exits remain visible. Leave the process running while you perform local checks.
The exact container names, volume definitions, host port mapping, startup timing, and generated development credentials are controlled by the repository version you checked out. Inspect the supplied Compose file rather than assuming those values remain identical across releases. This is especially important if you are following the guide against a branch or tagged release different from the current repository state.
Understand the dependencies started by Compose
PostgreSQL is required by the Svix server for event storage. Redis is used by configurations that select Redis for the queue and cache. Svix recommends enabling Redis persistence so tasks survive Redis restarts and upgrades. It also recommends an eviction policy that does not remove keys lacking explicit expiration settings. Suitable choices include noeviction or one of the available volatile policies.
These Redis details matter beyond initial startup. A container may appear to run correctly while an unsuitable persistence or eviction configuration creates operational risk later. Review the checked-out Compose configuration and adapt the storage arrangement before treating a development deployment as a durable environment.
Development setup versus a durable deployment
The Compose example is the documented easiest way to get Svix running, but ease of startup does not automatically make every default appropriate for internet-facing production use. Before handling real event data, review secret generation, database storage, Redis persistence, backups, container restart behavior, image version selection, resource limits, log retention, and upgrade procedures.
Use versioned images when your release process requires predictable upgrades. The Svix documentation allows either the latest image tag or a versioned tag. A latest tag can change as new images are published, while a versioned tag gives administrators a specific artifact to test and promote. The appropriate policy depends on your own release and security process.
Svix uses a JWT secret for authentication. It must be securely generated and kept private. Do not publish it in a repository, tunnel URL, Docker image, support message, or client-side application. Treat any example or development value as unsuitable for a real public deployment.
Understand the standalone Svix container alternative
Svix also documents running its official Docker image as a standalone container. This method publishes container port 8071 on host port 8071, but it is more advanced because the operator must supply working PostgreSQL and Redis connections and the required server configuration.
docker run \
--name svix-server \
-p 8071:8071 \
--env-file development.env \
svix/svix-server
The command expects a file named development.env in the current directory. That name is an example rather than a required universal filename. The file must contain values appropriate for your own deployment. Do not copy database credentials or JWT secrets from an untrusted example.
Svix supports three configuration mechanisms: environment variables, a .env file, and a TOML configuration file. A configuration file named config.toml in the server's current working directory is detected automatically. Equivalent environment-variable names use the uppercase configuration name with an SVIX_ prefix.
| Configuration concept | Environment-variable form | Purpose |
|---|---|---|
jwt_secret |
SVIX_JWT_SECRET |
Provides the secret used for JWT authentication and must be securely generated |
db_dsn |
SVIX_DB_DSN |
Points Svix to PostgreSQL, which is the supported event database |
redis_dsn |
SVIX_REDIS_DSN |
Points to Redis when Redis is used for the task queue and cache |
queue_type |
SVIX_QUEUE_TYPE |
Selects the message queue implementation used by the server |
A structural environment file can look like the following, but every placeholder must be replaced with a value designed for your network and security model. The example deliberately contains no working credentials.
SVIX_JWT_SECRET=<securely-generated-private-secret>
SVIX_DB_DSN=<postgresql-connection-string>
SVIX_REDIS_DSN=<redis-connection-string>
SVIX_QUEUE_TYPE=redis
Do not use the standalone command until the PostgreSQL hostname is resolvable from the container and the configured credentials permit the required database access. Apply the same test to Redis when using it. A hostname that works from the Docker host does not necessarily resolve from an isolated container, and localhost inside the Svix container refers to that container rather than automatically referring to another container or the host.
The standalone image does not package PostgreSQL and Redis into the same container. You are responsible for deploying those dependencies, creating their credentials, making them reachable from Svix, and preserving their data. Start with the supplied Compose workflow unless you already operate the required data services and understand the relevant container networking.
Verify Svix locally before exposing it
Verification should proceed in layers. First confirm that Docker started the expected services. Next check that the Svix server remains running instead of repeatedly exiting. Then confirm that the expected host port is actually published. Finally, perform an authenticated request defined by the Svix API documentation.
The supplied Svix installation excerpt does not establish a health-check path, a guaranteed response for the root URL, or a complete API request with authentication. We therefore should not invent a path such as /health, assume that opening the root address in a browser proves health, or provide a fabricated API payload.
Confirm that all expected containers remain active
Use your Docker interface to inspect the Compose project. The Svix server, PostgreSQL, and Redis services should not be continuously restarting or exiting. If a service stops, inspect its output before proceeding.
Review startup output for dependency errors
Look for failures involving the PostgreSQL DSN, Redis DSN, authentication configuration, schema initialization, file permissions, or port binding. Resolve the first underlying error rather than repeatedly restarting the stack.
Identify the published HTTP port
Read the checked-out Compose file or inspect Docker's published-port information. For the documented standalone command, host port 8071 maps to container port 8071. Do not assume that every Compose revision publishes the same host-side value without checking.
Test the listener from the future tunnel device
Confirm that the machine running our Localtonet client can establish an HTTP connection to the Docker host and published port. This catches host binding, local firewall, routing, and address-selection problems before a public tunnel is involved.
Complete a documented authenticated API operation
Use the current Svix API documentation and credentials generated for your deployment to select a valid endpoint and request. A successful authenticated operation is a stronger verification than receiving an arbitrary response from the root URL.
What different failures tell you
A connection-refused result generally means no process is listening on the selected address and port, the container port is not published to the host, or a local policy rejects the connection. A timeout more often points to routing or filtering. An HTTP response, including an authorization error, proves that an HTTP server answered, but it does not prove that the selected API operation is configured correctly.
An authentication failure should be handled as an application-layer issue. Check the current Svix authentication instructions, credential format, and server-side JWT configuration. Do not disable authentication merely to make a public test pass. Likewise, a database or queue error must be corrected within the Svix deployment rather than hidden behind retries at the tunnel layer.
Paths and response formats can change, and the supplied installation evidence does not document a health URL. Use the API operation and authentication procedure documented for the Svix version you deployed. A tutorial should not turn an assumed path into an operational dependency.
Expose the verified Svix HTTP API through Localtonet
Once the local listener and authenticated API operation work from the Localtonet client device, create an HTTP tunnel. HTTP is appropriate because the Svix API is an HTTP service. There is no need to publish a raw PostgreSQL port, Redis port, or the entire Docker network.
HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain as their Process Type. These options serve the same local content at a public HTTPS address. Availability can vary by the current product configuration or subscription, so use the choices shown in your dashboard. Exact custom-domain DNS instructions should be taken from the current Localtonet documentation rather than inferred.
Install and run the Localtonet client
Install our client on the Docker host or another device that can reach the verified Svix listener. Keep the client running because it establishes the outbound connection used by the tunnel.
Authenticate or select the client device
Use the device-specific Localtonet authentication token associated with the client that will carry this traffic. Do not guess, share, publish, or embed the token in application code.
Select an available relay server
Choose from the server or region values currently presented by our dashboard. Available values can vary, so this guide does not hardcode a relay server code.
Create an HTTP tunnel to the Svix listener
Select the HTTP tunnel family and enter the local IP address and host port verified earlier. If our client runs on the Docker host, use an address through which that host can reach the published port. If it runs elsewhere, use the Docker host's reachable network address.
Start the tunnel
Creating a tunnel does not mean it is running. Press Start and wait for the selected client and tunnel to show that they are connected before using the assigned public URL.
Test the public address and manage its lifecycle
Repeat the same documented Svix API operation against the assigned public HTTPS address while preserving the required authentication. Stop the tunnel when remote access is no longer needed, or delete it if the configuration should not be retained.
The public URL becomes the externally reachable base address for the tunneled Svix listener. Update only the server base address in your authorized remote client while retaining the correct API path, method, request body, and authentication required by Svix. Do not place an API credential in the URL query string unless Svix explicitly requires that format for the specific operation.
For the maintained product workflow, consult our Localtonet tunnel documentation. The dashboard is the authoritative place to obtain the device token association, available relay server choices, and current HTTP Process Type options.
The Svix public address is usable only while the selected Localtonet client is connected and the tunnel is running. If the client device shuts down, loses connectivity, or stops the client process, the public route will not remain available.
Secure a publicly reachable Svix deployment
Creating a tunnel changes reachability, not authorization. A service that was previously reachable only from the host can now receive traffic from the public internet. Review the Svix authentication model, credential storage, request validation, and operational controls before sharing the assigned URL.
Protect the Svix JWT secret and API credentials
The Svix JWT secret is part of the server's authentication foundation. Generate it securely, store it through an appropriate secret-management mechanism, and restrict access to the administrators and processes that require it. If it appears in source control, logs, screenshots, shell history, or support material, rotate it according to your deployment process.
Remote applications should receive only the credentials and permissions they need. Avoid embedding privileged server credentials in browser code, mobile applications, or downloadable configuration files. A public HTTPS address does not make a leaked credential less damaging.
Expose only the API listener
Point the HTTP tunnel at the published Svix service port. Do not create public tunnels for PostgreSQL or Redis as part of this workflow. Restrict database and queue access to the containers or internal systems that need it, and use separate administrative access controls for maintenance.
Plan persistence and backups
PostgreSQL stores Svix events, so its persistent data deserves a tested backup and recovery process. Redis persistence is recommended so queued tasks survive restarts and upgrades. Configure an eviction policy such as noeviction or an appropriate volatile policy so Redis does not evict keys that lack explicit expiration.
A container image is replaceable, but application state may not be. Verify where the checked-out Compose setup stores PostgreSQL and Redis data before removing containers, deleting volumes, changing hosts, or performing upgrades.
Control when the tunnel runs
For development, staging, demonstrations, or temporary integrations, stop the tunnel when the remote party no longer needs access. This reduces unnecessary exposure while allowing the Svix stack to remain available locally. Deleting a tunnel is appropriate when the public route should not be reused.
Do not assume that a development Compose configuration is ready for untrusted traffic. Replace development secrets, apply authentication, restrict credentials, maintain supported images, preserve data, monitor application behavior, and expose only the required HTTP listener. Localtonet provides the network route, while Svix remains responsible for authenticating and processing API requests.
Troubleshoot Svix Docker and Localtonet connectivity
Docker Compose cannot start
Confirm that Compose v2 is installed and that you are running the command from the repository's server directory. If Docker cannot find a Compose configuration, recheck the checkout location and directory structure. If Docker itself is unavailable, start or repair the Docker service before troubleshooting Svix.
The Svix container exits during startup
Read the server output and identify the first configuration or dependency error. Common categories include an unreachable PostgreSQL DSN, an unreachable Redis DSN, an invalid configuration value, a missing secret, or a port already bound by another process. Later errors can be consequences of the first failure, so correct the earliest root cause before restarting.
PostgreSQL or Redis cannot be reached
With the supplied Compose setup, verify that all services belong to the expected Compose project and that the dependency containers remain running. With standalone Docker, remember that you must supply working services and connection strings yourself. A loopback hostname inside the Svix container does not automatically refer to PostgreSQL or Redis running in another container.
Port 8071 is unavailable
The documented standalone command publishes host port 8071 to container port 8071. If another process already uses the host port, Docker cannot create that binding. Choose a deliberate host-side mapping that is free, document it, and use that actual host port as the Localtonet tunnel target. Do not change the internal container port without confirming that the Svix server configuration supports the change.
The service works on the Docker host but not from the Localtonet client device
This usually indicates that the client runs on another machine and is targeting an address that is local only to the Docker host. Test the Docker host's reachable LAN address and published port from the client device. Also inspect the host port binding and local network policy. Resolve this local path before changing the public tunnel.
The Localtonet tunnel exists but the public URL is unavailable
Check that the selected Localtonet client is connected and that the tunnel was started. Creation alone does not start it. Then verify that the configured local IP address and port exactly match the listener already tested from the client device. If the local test fails, the tunnel cannot deliver a successful response.
The public URL responds with an authentication error
An HTTP authentication response normally shows that the network path reached an application server. Repeat the documented Svix request with the correct authentication mechanism and credentials. Do not weaken server authentication or expose the JWT secret to make the test succeed.
A guessed browser URL returns 404
A 404 response does not necessarily mean the server is unhealthy. The root path may not be an API operation, and the supplied evidence does not define a browser landing page or health path. Use a real endpoint from the current Svix API documentation and include its required method, headers, credentials, and body.
The tunnel stops after a host restart
The tunnel depends on the selected Localtonet client being connected and the tunnel running. Confirm that the client has been started and authenticated again, then check the tunnel state. Separately confirm that Docker restored the Svix, PostgreSQL, and Redis services. Both the application stack and network route must be active.
Frequently asked questions
What is the easiest documented way to install the open-source Svix server?
The easiest documented method is to obtain the Svix repository, enter its server directory, and run docker compose up. The supplied Compose configuration also starts and configures PostgreSQL and Redis.
Does the standalone Svix Docker image include PostgreSQL and Redis?
No. The standalone container is the Svix server image. You must provide the required PostgreSQL service and the Redis service used by your configuration, then pass valid connection settings to the container.
Which port does the documented standalone container publish?
The documented standalone command maps host port 8071 to container port 8071. Check the supplied Compose file before assuming that a particular Compose revision publishes the same host-side port.
What health-check URL should I use for Svix?
The verified installation material used for this guide does not establish a health-check path. Do not assume one. Confirm container status and then perform an authenticated API operation documented for the Svix version you deployed.
Should I use an HTTP or TCP Localtonet tunnel for the Svix API?
Use an HTTP tunnel for this workflow because Svix exposes an HTTP API. Configure it to forward to the published local Svix address and port that you verified before creating the tunnel.
Does Localtonet replace Svix authentication?
No. Localtonet supplies the network route to the local HTTP listener. Svix must still authenticate and authorize API requests. Keep the JWT secret and API credentials private, and give remote applications only the access they require.
Do I need router port forwarding or a public IP address?
No. Our Localtonet client establishes an outbound connection to a relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Will the public Svix URL remain available when the client device is offline?
No. The tunnel is available only while the selected Localtonet client is connected and the tunnel is running. The Svix containers must also remain healthy and reachable from that client.
Should PostgreSQL or Redis also be exposed through a tunnel?
Not for this workflow. Expose only the Svix HTTP listener required by authorized API clients. Keep PostgreSQL and Redis on restricted internal networks unless you have a separate, carefully controlled administrative requirement.
Connect your verified Svix server with Localtonet
After Svix, PostgreSQL, and Redis are running correctly and an authenticated API operation succeeds locally, create an HTTP tunnel to the published Svix listener. Keep application credentials private and stop the tunnel whenever remote access is no longer required.
Get Started Free →
