Webhook Relay
Search…
🛠
Installation
WebSocket Server
Webhook Relay provides users an ability to directly subscribe to webhooks from their applications without using our stand-alone agent.
Socket server allows connecting to Webhook Relay service directly from your application using WebSocket protocol. Communication is done using JSON encoded messages. In order to start streaming, create a new bucket with your desired name.
Once you have a bucket, you can start receiving webhooks to your public endpoint (one public endpoint will be created by default upon bucket creation).
WebSockets will receive events with webhook data when both no outputs are defined or for every internal output specified. If you only have public outputs, neither WebSockets nor relay agent will receive them.
Protocol
Step 1: Connect
Your API keys allow multiple simultaneous connections. Connect to:
1
wss://my.webhookrelay.com/v1/socket
Copied!
Step 2: Authenticate
You must authenticate before you can make any other requests. Generate a new key & secret pair in your tokens page (https://my.webhookrelay.com/tokens). To authenticate, send:
1
{
2
"action":"auth",
3
"key":"YOUR_KEY",
4
"secret":"YOUR_SECRET"
5
}
Copied!
Once authenticated, you will receive the following message:
1
{
2
"type": "status",
3
"status": "authenticated",
4
"message": "connected successfully, subscribe to buckets"
5
}
Copied!
Step 3: Subscribe to webhooks stream
Once authenticated, you can request a stream. Buckets (https://my.webhookrelay.com/buckets) are used for grouping and routing. You can request multiple bucket streams. To subscribe, send:
1
{
2
"action":"subscribe",
3
"buckets": [ "my-1-bucket-name", "my-2-bucket-id" ]
4
}
Copied!
Fieldbucketsworks as a filter, checking for bucket ID or bucket name. To subscribe to all buckets in your account, send only{"action":"subscribe"}message.
Once subscribed, you will receive the following message, confirming your stream:
1
{
2
"type": "status",
3
"status": "subscribed",
4
"message": "subscribed to buckets: my-1-bucket-name, my-2-bucket-id"
5
}
Copied!
Schema
All incoming webhooks will have event type set to
webhook and attached meta field with additional information such as bucket ID, bucket name, input ID, input name:1
{
2
"type": "webhook", // event type
3
"meta": { // bucket, input and output information
4
"bucked_id": "1593fe5f-45f9-45cc-ba23-675fdc7c1638",
5
"bucket_name": "my-1-bucket-name",
6
"input_id": "b90f2fe9-621d-4290-9e74-edd5b61325dd",
7
"input_name": "Default public endpoint",
8
"output_name": "111",
9
"output_destination": "http://localhost:8080"
10
},
11
"headers": { // request headers
12
"Content-Type": [
13
"application/json"
14
]
15
},
16
"query": "foo=bar", // query (ie: /some-path?foo=bar)
17
"body": "{\"hi\": \"there\"}", // request body
18
"method": "PUT" // request method
19
}
Copied!
Answering to pings
In order to ensure that idle connections are not cut by the load balancers and routers, our servers are constantly sending both WebSocket protocol pings and regular messages over the open connection. For better availability, please add handler in your WebSocket client that responds to:
1
{
2
"action": "ping"
3
}
Copied!
with a:
1
{
2
"action": "pong"
3
}
Copied!
JavaScript Example
Here's a short example application written in JavaScript that subscribes to a stream of webhooks:
1
// client.js
2
const WebSocket = require('ws');
3
4
var server = 'wss://my.webhookrelay.com/v1/socket';
5
var reconnectInterval = 1000 * 3;
6
var ws;
7
8
var apiKey = process.env.RELAY_KEY;
9
var apiSecret = process.env.RELAY_SECRET;
10
11
var connect = function(){
12
ws = new WebSocket(server);
13
ws.on('open', function() {
14
console.log('connected, sending authentication request');
15
ws.send(JSON.stringify({ action: 'auth', key: apiKey, secret: apiSecret }));
16
});
17
18
ws.on('message', function incoming(data) {
19
console.log(data)
20
21
// parse message and if we have authenticated, subscribe to our bucket
22
var msg = JSON.parse(data);
23
if (msg.type === 'status' && msg.status === 'authenticated') {
24
ws.send(JSON.stringify({ action: 'subscribe', buckets: ['my-bucket'] }));
25
}
26
});
27
28
ws.on('error', function() {
29
console.log('socket error');
30
});
31
32
ws.on('close', function() {
33
console.log('socket closed, reconnecting');
34
setTimeout(connect, reconnectInterval);
35
});
36
};
37
38
connect();
Copied!
To run:
1. Install websocket library ws:
1
npm i ws
Copied!
2. Set token key and secret (from tokens page):
1
export RELAY_KEY=your-token-key
2
export RELAY_SECRET=your-token-secret
Copied!
3. Start it:
1
node client.js
Copied!
Now, if you send a webhook to your public input endpoint, you should see something similar:
1
$ node client.js
2
{"type":"status","status":"authenticated","message":"connected successfully, subscribe to buckets"}
3
{"type":"status","status":"subscribed","message":"subscribed to buckets: 123"}
4
{"type":"webhook","meta":{"bucked_id":"89e44c32-27ff-4832-8655-8a42d3851b6f","bucket_name":"123","input_id":"ee4ac550-12a4-41a7-837d-dd3356ed1771","input_name":"Default public endpoint"},"headers":{"Content-Length":["15"],"User-Agent":["insomnia/6.0.2"],"Cookie":["__cfduid=dc244a014f0b1e2965544ddb483c3fe1b1525866866"],"Content-Type":["application/json"],"Accept":["*/*"]},"query":"","body":"{\"hi\": \"there\"}","method":"PUT"}
Copied!
JavaScript SDK example
Javascript library is available via
npm. Library source code is available on GitHub. It's written in Typescript is a thin wrapper around our WebSocket server client. It can only subscribe to buckets but cannot create/update/delete them.To install it:
1
npm i webhookrelay-ws-client
Copied!
Library usage
1
var ws = require(`webhookrelay-ws-client`);
2
3
// handler function has to accept a JSON string and parse on its own
4
var handler = function (data) {
5
console.log(data)
6
}
7
8
// create a client with specified token key and secret from https://my.webhookrelay.com/tokens and any buckets that
9
// can be created here https://my.webhookrelay.com/buckets. Handler function is called whenever there's a new message
10
var client = new ws.WebhookRelayClient('your-token-key', 'your-token-secret', ['bucket-1', 'bucket-2'], handler)
11
12
// connect starts a websocket connection to Webhook Relay
13
client.connect();
Copied!
Example application
Set tokens as environment variables:
1
export RELAY_KEY=[YOUR TOKEN KEY]
2
export RELAY_SECRET=[YOUR TOKEN SECRET]
Copied!
1
// app.js
2
var ws = require(`webhookrelay-ws-client`);
3
4
var apiKey = process.env.RELAY_KEY;
5
var apiSecret = process.env.RELAY_SECRET;
6
7
var handler = function (data) {
8
console.log(data)
9
}
10
11
var run = function () {
12
var client = new ws.WebhookRelayClient(apiKey, apiSecret, ['nodered'], handler)
13
client.connect();
14
15
// do some work
16
17
// disconnect whenever connection is no longer needed
18
setTimeout(function(){
19
console.log('disconnecting')
20
client.disconnect();
21
}, 10000);
22
}
23
24
run();
Copied!
To run it:
1
node app.js
Copied!
Now, whenever you send webhooks to your public endpoint
https://my.webhookrelay.com/v1/webhooks/<your input ID>, they will be received inside your application. You can subscribe to multiple buckets. Each message will have a JSON string that you can parse:1
{
2
"type": "webhook", // event type
3
"meta": { // bucket, input and output information
4
"bucked_id": "1593fe5f-45f9-45cc-ba23-675fdc7c1638",
5
"bucket_name": "my-1-bucket-name",
6
"input_id": "b90f2fe9-621d-4290-9e74-edd5b61325dd",
7
"input_name": "Default public endpoint",
8
"output_name": "111",
9
"output_destination": "http://localhost:8080"
10
},
11
"headers": { // request headers
12
"Content-Type": [
13
"application/json"
14
]
15
},
16
"query": "foo=bar", // query (ie: /some-path?foo=bar)
17
"body": "{\"hi\": \"there\"}", // request body
18
"method": "PUT" // request method
19
}
Copied!
Last modified 1yr ago