Introduction

What is Web Relay?

Web Relay (also known as Webhook Relay) is a tunneling service for creating reverse tunnels for one-way or bidirectional data transfer to internal services (running on your laptop, an internal JIRA/Bitbucket server in your private network). Web Relay is designed to be easy-t-start-with and remain flexible enough for advanced use cases. The core webhookrelayd agent uses a combination of GRPC protocol based service and raw encrypted TCP connections for performance. Web Relay is perfectly capable of powering sophisticated use cases where performance and dynamic routing configuration is required.

Webhooks

Getting Started

The official guide assumes beginner level knowledge of terminal, networks and web applications.

The easiest way to try out Web Relay is by using the relay command client..

The Installation page provides more options of installing the CLI. Please note, that we do recommend that beginners start with relay, especially if they are not yet familiar with daemons or Docker.

CREATE ACCOUNTfree plan available, no credit card required

Using CLI

Relay CLI was modeled against Docker’s CLI so command structure should be familiar.
To list available commands, use help:

$ relay help
Usage: relay COMMAND
Webhook Relay - tunnels for webhooks to internal and public services.
By using this product, you are agreeing to the terms of the the AppScension Ltd. Terms of service can be found at: https://webhookrelay.com/terms/
Don't have an account? Create one here: https://my.webhookrelay.com/register
Options:
--config string Location of client config files (default "/Users/karolisrusenas/.webhookrelay")
--help Print usage
--tls Use TLS; implied by --tlsverify (default true)
--tlsverify Use TLS and verify the remote
-v, --version Print version information and quit
Management Commands:
bucket Manage buckets - used to group inputs and outputs together
input Manage inputs - your personal endpoints to receive webhooks
output Manage outputs - destinations where requests are relayed
token Manage tokens - required for API (OAuth users) and webhook streaming connections
tunnel Manage tunnels - bidirectional connections that expose internal services (EXPERIMENTAL)
Commands:
connect Connects a supplied destination to the public endpoint
forward Create a forwarding configuration (automatically creates bucket, input endpoint and output destination). If destination and bucket aren't specified - starts a relay for all endpoints
login Log in to a Webhook Relay service
logout Log out from a Webhook Relay service
Run 'relay COMMAND --help' for more information on a command.

Authentication

In order to start using the service, you will need to create an account. If you already have an account, skip this section. Head to the registration page https://my.webhookrelay.com/register and register.
Relay CLI needs credentials for your account. If you have standard username/password account, you can use same credentials. If you are using OAuth to authenticate, generate a token.

$ relay login
Username (John): John
Password:

Another option is to set environment variables:

export RELAY_USERNAME=yourusername
export RELAY_PASSWORD=boo

Webhook Forwarding

At the core of Web Relay is a webhook delivery system that enables one-way HTTP request forwarding to the destination. Once webhook is accepted, it will be forwarded to all outputs listed in the bucket. To start forwarding:

$ relay forward -b webhook-demo http://localhost:8090/webhook
Forwarding:
https://my.webhookrelay.com/v1/webhooks/5e722a5e-f3d2-4hqec-9e9f-79f1158e4b10 -> http://localhost:8090/webhook
starting webhook relay agent...

We have already created our very first configuration for webhook forwarding! Any request that hits https://my.webhookrelay.com/v1/webhooks/5e722a5e-f3d2-4hqec-9e9f-79f1158e4b10 endpoint will be forwarded to locally running application reachable on http://localhost:8090/webhook address. Headers, method and body will be preserved.

Tunnels

Another core feature of Web Relay are bidirectional tunnels that allow traffic to go both ways. If we want to connect to the same application reachable locally on http://localhost:8090 address, then use connect command:

$ relay connect --name www http://localhost:8090/
Connecting:
http://9nqwqvl6hmgofqcxkvjcjd.webrelay.io <----> http://localhost:8090/
1.5111323749546723e+09 info client starting {"version": "develop"}
1.5111323760509975e+09 info adding HTTP tunnel 9nqwqvl6hmgofqcxkvjcjd.webrelay.io ---> http://localhost:8090/
1.5111323760511322e+09 info tunnel proxy configuration updated

That’s it! A new personal subdomain will be generated and you can access your locally running service through the public endpoint here. In this example the generated host is http://9nqwqvl6hmgofqcxkvjcjd.webrelay.io.

Please note that custom subdomains are also available.

Ready for More?

We’ve briefly introduced the most basic features of Web Relay - the rest of this guide will cover them as well as other advanced features with much finer details. Please make sure to read through it all!