Quick Start

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. Web Relay is perfectly capable of powering sophisticated use cases where performance and dynamic routing configuration is required.

Webhooks

Getting Started

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

Linux users

curl -sSL https://storage.googleapis.com/webhookrelay/downloads/relay-linux-amd64 > relay \
&& chmod +wx relay && sudo mv relay /usr/local/bin

MacOS users

curl -sSL https://storage.googleapis.com/webhookrelay/downloads/relay-darwin-amd64 > relay \
&& chmod +wx relay && sudo mv relay /usr/local/bin

Windows

  1. You can download the latest release from the link below:
    https://storage.googleapis.com/webhookrelay/downloads/relay-windows-amd64.exe.

    Or if you have curl installed, use this command:

    curl -LO https://storage.googleapis.com/webhookrelay/downloads/relay-windows-amd64.exe
  2. Add the binary in to your PATH.

Registration & 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:

CREATE ACCOUNTfree plan available, no credit card required

Relay CLI needs credentials for your account. Once registered, generate a token and use token key and secret as a username and password for CLI authentication:

Create Token

And then use it:

relay login -k token-key-here -s token-secret-here

Another option is to set environment variables:

export RELAY_KEY=token-key
export RELAY_SECRET=token-secret

10 second explanation on Webhook Configuration

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.

All webhooks will appear in your bucket logs:

Bucket Page

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 for paid plans.

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.