research-webhookrelay-websocket-20260128

Date: 2026-01-28 Research Request: From James Lee - Understanding WebhookRelay WebSocket delivery and Node.js SDK support

TL;DR

Yes, WebhookRelay supports WebSocket-based webhook delivery. You can receive webhooks without exposing a public HTTP endpoint on your infrastructure. WebhookRelay provides an official Node.js SDK called webhookrelay-ws-client available on npm, making it straightforward to implement in Node.js applications.

How WebhookRelay WebSocket Architecture Works

The Problem It Solves

Traditional webhook delivery requires your application to have:

• A publicly accessible HTTP endpoint
• A public IP address or reverse proxy
• NAT/firewall configuration
• Running web server infrastructure

WebhookRelay’s WebSocket approach eliminates these requirements.

Connection Architecture

External Service → WebhookRelay Public HTTP Endpoint
                       ↓ (stores webhook)
                  (your application initiates)
Your App ←→ WebhookRelay WebSocket Server
                  (persistent connection)

How it works:

1. Setup Phase:

   • You create a “bucket” in WebhookRelay (acts as a webhook receiver)
   • WebhookRelay assigns you a public HTTP endpoint (e.g., https://my.webhookrelay.com/webhooks/abc123)
   • Your application obtains authentication token and secret

2. Connection Establishment:

   • Your Node.js application initiates an outbound WebSocket connection to wss://my.webhookrelay.com/v1/socket
   • The connection is persistent and maintained by your application (no firewall rules needed)
   • Your app sends authentication credentials via JSON: { "action": "auth", "key": "your_key", "secret": "your_secret" }

3. Subscription:

   • After authentication, your app sends a subscription message: { "action": "subscribe", "buckets": ["bucket_name"] }
   • WebhookRelay confirms subscription

4. Webhook Delivery:

   • External services POST webhooks to your public endpoint: POST https://my.webhookrelay.com/webhooks/abc123
   • WebhookRelay stores the webhook and routes it through the open WebSocket connection
   • Your application receives the webhook as a JSON message containing:
     • Full request headers
     • Request body/payload
     • Query parameters
     • HTTP method (GET, POST, etc.)
     • Metadata about the delivery

5. Connection Lifecycle:

   • Connection remains open until explicitly closed
   • Automatic reconnection with exponential backoff if connection drops
   • Handles multiple simultaneous webhooks through the same WebSocket

Key Advantages Over HTTP Polling

• No public HTTP server required - only an outbound WebSocket connection
• Real-time delivery - webhooks arrive immediately through persistent connection
• Firewall-friendly - outbound WebSocket connection bypasses most firewall restrictions
• Efficient - no polling overhead, lower latency than polling strategies
• Scalable - WebhookRelay handles load balancing and connection management

Node.js SDK: webhookrelay-ws-client

Official Package

Package Name: webhookrelay-ws-client NPM: https://www.npmjs.com/package/webhookrelay-ws-client GitHub: https://github.com/webhookrelay/webhookrelay-ws-client Latest Version: 0.7.1 License: Apache-2.0 Language: TypeScript (97.8% of codebase)

Installation

npm install webhookrelay-ws-client

Basic Usage Example

const WebhookRelayClient = require('webhookrelay-ws-client').default;

// Initialize client with credentials
const client = new WebhookRelayClient({
  token: 'your_api_token',
  secret: 'your_api_secret'
});

// Subscribe to bucket and handle incoming webhooks
client.subscribe('your_bucket_name', (webhook) => {
  // webhook object contains:
  // - headers: incoming request headers
  // - body: parsed request body
  // - query: query parameters
  // - method: HTTP method (POST, GET, etc.)
  // - meta: metadata about delivery

  console.log('Received webhook:', webhook);

  // Process the webhook
  // This runs inside your application, no HTTP server needed
});

// Connect to WebhookRelay
client.connect();

// When done:
// client.disconnect();

Key API Methods

• subscribe(bucketName, handler) - Subscribe to a bucket and receive webhooks

  • bucketName (string) - The bucket to listen to
  • handler (function) - Callback function invoked when webhooks arrive
  • Supports subscribing to multiple buckets

• connect() - Establish WebSocket connection to WebhookRelay

• disconnect() - Close WebSocket connection

Features

• ✅ WebSocket-based delivery (no HTTP server required)
• ✅ Subscribe to multiple buckets simultaneously
• ✅ Automatic connection management
• ✅ Handles reconnection with exponential backoff
• ✅ TypeScript types included
• ✅ Apache-2.0 licensed (open source)

Limitations

• Read-only operations for bucket subscriptions
• Cannot create/update/delete buckets through this client (use WebhookRelay API for management)
• Last release: February 2020 (consider checking for more recent versions or active maintenance)

Alternative: Native WebSocket Implementation

If you prefer not to use the SDK, you can implement WebSocket connections directly using Node.js’s native WebSocket library (ws):

const WebSocket = require('ws');

const ws = new WebSocket('wss://my.webhookrelay.com/v1/socket');

ws.on('open', () => {
  // Authenticate
  ws.send(JSON.stringify({
    action: 'auth',
    key: 'your_key',
    secret: 'your_secret'
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);

  if (message.action === 'authenticated') {
    // Subscribe to buckets
    ws.send(JSON.stringify({
      action: 'subscribe',
      buckets: ['your_bucket_name']
    }));
  } else if (message.action === 'webhook') {
    // Process incoming webhook
    console.log('Webhook received:', message.data);
  }
});

ws.on('error', (error) => {
  console.error('WebSocket error:', error);
});

Comparison Summary

Recommendation for James’s Use Case

WebhookRelay’s WebSocket approach is ideal for your scenario where you want to:

• ✅ Receive webhooks without exposing a public HTTP server
• ✅ Avoid NAT/firewall configuration complexity
• ✅ Keep all webhook processing inside your Node.js application
• ✅ Have a simple, straightforward setup

The webhookrelay-ws-client SDK provides the smoothest developer experience for Node.js. If you need bucket management capabilities, combine it with the WebhookRelay REST API.

Sources

• WebSocket Server Documentation - WebhookRelay
• Introducing WebSocket Server Blog Post
• webhookrelay-ws-client on npm
• webhookrelay-ws-client GitHub Repository
• WebhookRelay JavaScript Examples