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 (https://my.webhookrelay.com/tokens). 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 (https://my.webhookrelay.com/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