Security & Tech

Webhook Relay is designed to increase network security by allowing internal services to receive webhooks and HTTP connections without exposing entire servers to the Internet.

Each user gets one or more public URL endpoints (we call them inputs and they are grouped in buckets). When Webhook Relay agents connect to our servers, they have to authenticate using token key & secret pair and provide a list of buckets that they want to subscribe to. Once our servers receive a webhook, it’s routed based on input ID to one or more agents:

In this document, we will address the most common questions about the system, protocols involved, and security policies.

Endpoints

All input endpoints are created based on UUID (universally unique identifiers) and can only belong to one bucket. Buckets can enable basic (username & password) or token-based authentication for all inputs. Both existing and non-existent input endpoints by default will return response status code 200.

Responses

By default, webhook forwarding is unidirectional. This means that responses from the destination will not be returned to the caller. This acts as a security layer, isolating your system and ensuring that the caller doesn’t know what kind of system (if there is any) is receiving the webhooks. This is useful since most of the services are using response headers to identify themselves and libraries used to implement HTTP stack.

Optionally, you can configure inputs to return static, dynamic (created by Functions) or wait for the destination to respond before returning HTTP response.

Connections

For internal destinations, a Webhook Relay agent is required. It’s available as a Linux/Windows/macOS executable that can configure itself as an operating system background service or Docker container. You can view installation instructions here.

The agent opens a GRPC connection to our public servers. Any webhooks, received by our servers will be matched to agents and streamed. Alternatively, a WebSocket connection can be used. All connections use TLS (Transport Layer Security), therefore traffic is always encrypted in transit. For connections, token authentication is required.

High Availability

Webhook Relay servers run on Google Cloud Kubernetes platform to achieve high-availability. The agent uses health checks for connection monitoring and after reconnect (if your server reboots) it will resend missed webhooks from the last 10 minutes that weren’t sent yet.

It is recommended to run Webhook Relay agent in a container scheduler such as Kubernetes, OpenShift, Nomad, Swarm to ensure that it’s always online.

Protocol

Communication protocol for webhook forwarding is either GRPC or WebSockets. You can view our Socket Server documentation for message format. The protocol only allows HTTP requests, so your servers will never be exposed to SSH or other vulnerabilities even if your SaaS account was compromised.

Agents also can’t be switched between tunnel (bidirectional) and webhook forwarding modes via API, it has to be chosen during the installation.

Passwords, Tokens

We use bcrypt for password and token secret hashing, therefore if you lose your token secret, you will need to create a new one as they are not recoverable.

Data Storage

Webhook data is encrypted with AES-256 at rest. All buckets have also an option to become ‘ephemeral’ which means that body, headers, and query arguments are never stored in the database. Only the status code and time will be stored for audit and billing purposes.

Alternatively, a self-hosted version of Webhook Relay is available if you want to keep data on your Own servers.