Socket Server

Socket server allows connecting to Webhook Relay service directly from your application using WebSockets. Communication is done using JSON encoded messages. In order to start streaming, create a new bucket with your desired name:

New Bucket

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.

Step 1: Connect

Your API keys allow multiple simultaneous connections. Connect to:


Step 2: Authenticate

You must authenticate before you can make any other requests. Generate a new key & secret pair in your tokens page ( To authenticate, send:


Once authenticated, you will receive the following message:

"type": "status",
"status": "authenticated",
"message": "connected successfully, subscribe to buckets"

Step 3: Subscribe to webhooks stream

Once authenticated, you can request a stream. Buckets ( are used for grouping and routing. You can request multiple bucket streams. To subscribe, send:

"buckets": [ "my-1-bucket-name", "my-2-bucket-id" ]

Field buckets works 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:

"type": "status",
"status": "subscribed",
"message": "subscribed to buckets: my-1-bucket-name, my-2-bucket-id"


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:

"type": "webhook", // event type
"meta": { // bucket, input and output information
"bucked_id": "1593fe5f-45f9-45cc-ba23-675fdc7c1638",
"bucket_name": "my-1-bucket-name",
"input_id": "b90f2fe9-621d-4290-9e74-edd5b61325dd",
"input_name": "Default public endpoint",
"output_name": "111",
"output_destination": "http://localhost:8080"
"headers": { // request headers
"Content-Type": [
"query": "foo=bar", // query (ie: /some-path?foo=bar)
"body": "{\"hi\": \"there\"}", // request body
"method": "PUT" // request method

JavaScript Example

Here’s a short example application written in JavaScript that subscribes to a stream of webhooks:

// client.js
const WebSocket = require('ws');
var server = 'wss://';
var reconnectInterval = 1000 * 3;
var ws;
var apiKey = process.env.RELAY_KEY;
var apiSecret = process.env.RELAY_SECRET;
var connect = function(){
ws = new WebSocket(server);
ws.on('open', function() {
console.log('connected, sending authentication request');
ws.send(JSON.stringify({ action: 'auth', key: apiKey, secret: apiSecret }));
ws.on('message', function incoming(data) {
// parse message and if we have authenticated, subscribe to our bucket
var msg = JSON.parse(data);
if (msg.type === 'status' && msg.status === 'authenticated') {
ws.send(JSON.stringify({ action: 'subscribe', buckets: ['my-bucket'] }));
ws.on('error', function() {
console.log('socket error');
ws.on('close', function() {
console.log('socket closed, reconnecting');
setTimeout(connect, reconnectInterval);

To run:

1. Install websocket library ws:

npm i ws

2. Set token key and secret (from tokens page):

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

3. Start it:

node client.js

Now, if you send a webhook to your public input endpoint, you should see something similar:

$ node client.js
{"type":"status","status":"authenticated","message":"connected successfully, subscribe to buckets"}
{"type":"status","status":"subscribed","message":"subscribed to buckets: 123"}
{"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"}