- Use Case
- Log in →
- Security & Tech
- Webhook Forwarding
- Functions (transform)
- Exec Commands
- WebSocket Server
- HTTP Tunnels
- TLS Tunnels
- Global Infrastructure
Internet of Things
- Home Automation
- Internet of Things (IoT)
- CLI commands
- Proxy Configuration
- Self-hosted deployment
- Client configuration
Webhook Relay provides public endpoints which can accept webhooks and then, based on user defined rules, forward them to either public or internal destinations.
Our service has a concept of bucket which is basically a grouping mechanism that enables you to accept webhooks on multiple endpoints and forward them to one or more destinations. Bucket inputs are configurable and can return custom responses, while outputs can have filtering rules and forward webhooks to both internal or public destinations:
A newly created bucket will have a default input and will request you to create an output destination:
If it’s a public destination, add the name, HTTP URL and click ‘create output’. All received webhooks will be forwarded to that destination.
If it’s an internal destination, check ‘internal network’ and start a
$ relay forward --bucket new http://localhost:8080
Currently Webhook Relay forwards:
- Body (up to 3MB)
- URL query, for example
https://my.webhookrelay.com/v1/webhooks/2e50b993-ac45-48f7-b840-eb054b19e630?foo=bar, will be forwarded to
- Extra path that’s after your public input endpoints:
https://my.webhookrelay.com/v1/webhooks/2e50b993-ac45-48f7-b840-eb054b19e630/directory/foowill be forwarded to
Buckets can be configure to be ephemeral so that request method, headers, query and body will not be saved to the database. To do this, go to bucket details page, click on Configure button and tick Ephemeral webhooks box. All new webhooks will not have their details saved. When ephemeral mode is on, you will not be able to:
- view request details
- resend webhook
New webhook logs will appear like this:
Sometimes applications that send webhooks accept certain headers, status code or body. To configure these settings, go to your bucket details and click on a settings icon near the input URL that you want to configure:
Configuration looks like:
You can specify from which output should the response be returned to the caller. By default no response is returned to keep internal services more secure/private. However, you can choose some specific output or any output (whichever returns first). Outputs should return response within 10 seconds window, otherwise Webhook Relay will not wait for the response.
To select response, go to your bucket details page, click on the input settings and select the output from the dropdown:
Functions, when applied on Inputs can provide dynamic response. See functions documentation.
Output configuration allows overriding request headers so users can add any headers on top:
You can also update output destination and headers through CLI:
relay output update OutputName --bucket Test --header secret-token=123456 --destination https://127.0.0.1:1880
Configurable timeouts let you deal with slow servers. To modify request timeout, go to bucket details, then in the outputs tab open settings (request timeout is configure for each output destination):
You can control TLS verification for each output individually. To enable or disable TLS verification, go to your output settings:
Rules can be applied on each output to filter incoming requests. There are a number of different configurations that allow:
- Match based on request body contents (such as
does not containrule types)
- Match based on parsed JSON body
- Regex match based on URL query, headers or parsed JSON body
- Simple equality check based on URL query, headers or parsed JSON body
Below, there are several examples to do matching based on URL queries and request bodies.
Let’s create a rule that checks whether URL query has a specific parameter that matches our given value:
With this configuration, if we send a webhook to https://my.webhookrelay.com/v1/webhooks/aa4d6bb5-87b6-4041-b5f4-a768338425c6?name=john, rule will extract and match parameters
https://my.webhookrelay.com/v1/webhooks/...?name=john will be matching the rule, a webhook to
https://my.webhookrelay.com/v1/webhooks/...?name=tom will not be relayed.
To match based on regular expressions, select
regex rule type:
With this configuration, a webhook request query will have to have a
location parameter with value either
You can view regex examples here: https://golang.org/pkg/regexp/syntax/
Contains or Does Not Contain
There are additional matching types such as contains and does not contain. These are general purpose, easy to use matchers.
Body matching can be achieved by:
- value based matching
- regex matching of parsed body into a JSON object
- contains matching that looks for a specified text in the body
- does not contain matching that checks whether body doesn’t have a specified word/phrase
Value type rule can match a parsed payload of a JSON webhook and check whether a specified parameter matches the rule value:
Only webhooks that have
id = foo inside the nested ‘data’ key will be passed:
Regex rules can match based on specified parameters when JSON body is parsed:
With this configuration, a request with payload:
will be matched by a rule and passed through, while this one:
will be rejected as it contains our unwanted value.
Contains matching is one of the simplest examples:
contains rule type and type a string that should be in the request body:
This payload will be relayed.
If body is not JSON, ‘contains’, ‘regex’ or ‘does not contain’ will be matching against plain text body.
Similarly to URL query and request body matching, header rules can extract and compare values from headers:
Rules can perform both SHA1 and SHA256 webhook payload signature validation. For that, you need to choose header as the source, set parameter to the name of the header that will have the hash, select either ‘payload SHA1’ or ‘payload SHA256’ from the menu and set your secret in the value field:
Rules can be grouped using logical operators all and any which are equivalent to and and or if you are familiar with programming principles. You can have multiple levels of rules interacting with each other.