跳转到内容

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。

服务端消息类型

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

类型	说明
`connected`	连接建立后立即下发，可带简单 `payload`（如连接 id）。
`new_request`	有请求命中 `/h/:endpointId` 时触发；`payload` 为捕获的请求（方法、路径、头、查询、正文等）。
`error`	连接或处理错误说明。
`pong`	对客户端 `ping` 的响应。

心跳 `ping` / `pong`

发送文本帧：

{ "type": "ping" }

服务端示例响应：

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

示例

浏览器
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('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);

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