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