Skip to content

WebSocket API

Subscribe to live webhook events for an endpoint with one long-lived connection. You need an API key created in the web app.

Connection URL

wss://api.hooknexus.com/ws/:endpointId?apikey=<your_api_key>

Replace :endpointId with your endpoint’s ID (UUID from the dashboard).
Replace <your_api_key> with the secret you copied when the key was created (URL-encode it if it contains special characters).

The key must belong to the same account as the endpoint, and your plan must allow API keys and WebSocket usage.

Server message types

Messages are JSON with a type field and a numeric timestamp (milliseconds).

Type	Purpose
`connected`	Sent right after the connection opens; may include a small `payload` (for example a connection id).
`new_request`	Fired when a webhook hits your `/h/:endpointId` URL; `payload` contains the captured request (method, path, headers, query, body, etc.).
`error`	Describes a connection or processing error.
`pong`	Reply to a client `ping`.

Client `ping` / `pong`

Send a JSON text frame:

{ "type": "ping" }

The server responds with:

{ "type": "pong", "timestamp": 1711180800123 }

Examples

Browser
Node (ws)

const endpointId = 'YOUR_ENDPOINT_ID';
const apiKey = 'YOUR_API_KEY';

const ws = new WebSocket(
  `wss://api.hooknexus.com/ws/${endpointId}?apikey=${encodeURIComponent(apiKey)}`
);

ws.addEventListener('open', () => {
  console.log('connected');
});

ws.addEventListener('message', (ev) => {
  const msg = JSON.parse(ev.data);
  if (msg.type === 'new_request') {
    console.log('Webhook:', msg.payload?.method, msg.payload?.body);
  }
});

const WebSocket = require('ws');

const ws = new WebSocket(
  `wss://api.hooknexus.com/ws/${process.env.ENDPOINT_ID}?apikey=${process.env.HOOKNEXUS_API_KEY}`
);

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'new_request') {
    console.log(JSON.stringify(msg.payload, null, 2));
  }
});

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }));
  }
}, 25000);

Example `new_request` envelope

{
  "type": "new_request",
  "timestamp": 1711180800123,
  "payload": {
    "id": "log-uuid",
    "method": "POST",
    "path": "/h/your-endpoint-id",
    "headers": { "content-type": "application/json" },
    "query": {},
    "body": "{}",
    "contentType": "application/json",
    "ip": "203.0.113.10",
    "size": 2,
    "createdAt": "2026-03-23T12:00:00.000Z"
  }
}