WebSocket API

使用 WebSocket 订阅某个端点上的实时 Webhook。需要先在网页中创建 API Key。

连接地址

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

:endpointId 替换为控制台中的端点 UUID。
<your_api_key> 替换为创建 Key 时复制的完整密钥（必要时 URL 编码）。

Key 须属于该端点所在账号，且当前套餐允许 API Key 与 WebSocket。

该连接会占用该 endpoint 的 WebSocket 并发数，与 Dashboard、CLI 等其他在线监听端共享同一上限。

服务端消息类型

消息为 JSON，含 type 与数值型 timestamp（毫秒）。

类型	说明
`connected`	连接建立后立即下发，可带简单 `payload`（如连接 id）。
`new_request`	有请求命中 `/h/:endpointId` 时触发；`payload` 为捕获的请求（方法、路径、头、查询、正文等）。
`replay_request`	当 Dashboard 将历史请求下发到当前这个非 Web 客户端时触发；`payload.request` 为原始请求快照。
`error`	连接或处理错误说明。
`pong`	对客户端 `ping` 的响应。

心跳 `ping` / `pong`

发送文本帧：

{ "type": "ping" }

服务端示例响应：

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

如果你的客户端暂时只关心实时请求，建议忽略未知 type，这样后续协议扩展时无需立刻改代码。

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('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 endpointId = process.env.ENDPOINT_ID;
const apiKey = process.env.HOOKNEXUS_API_KEY;

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

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

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

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

ws.on('close', (code, reason) => {
  console.log('closed', code, reason.toString());
});

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

需要一个可直接复制运行、附带测试 curl 的版本，可参考 Node.js API Key 监听示例。

`new_request` 示例

{
  "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"
  }
}

`replay_request` 示例

{
  "type": "replay_request",
  "timestamp": 1711180800999,
  "payload": {
    "replayId": "replay_123",
    "sourceRequestId": "log-uuid",
    "dispatchedAt": "2026-03-28T10:00:00.000Z",
    "target": {
      "connectionId": "conn_123",
      "clientType": "api_key",
      "clientMode": null,
      "connectedAt": 1711180800000,
      "userAgent": null
    },
    "request": {
      "id": "log-uuid",
      "endpointId": "your-endpoint-id",
      "method": "POST",
      "path": "/h/your-endpoint-id",
      "headers": { "content-type": "application/json" },
      "query": {},
      "body": "{}",
      "contentType": "application/json",
      "ip": "203.0.113.10",
      "userAgent": "stripe/1.0",
      "size": 2,
      "createdAt": "2026-03-23T12:00:00.000Z"
    }
  }
}