Webhook 通知接入文档

当网站、API 或设备监控状态发生变化时，咕咕监控可以向你的业务系统发送 HTTP 回调，方便接入内部告警、工单、群机器人或自动化处理流程。

配置入口：在 App、微信小程序或网页管理后台进入通知通道设置，开启 Webhook 通知，填写接收地址和签名密钥。每个监控项也可以单独开启或关闭 Webhook 通知。

请求方式

咕咕监控向你配置的 URL 发起 HTTP POST。
请求体为 JSON，编码为 UTF-8。
请求头包含 Content-Type: application/json。

响应要求

建议接收端返回 HTTP 2xx。
超时时间为 10 秒。
如果接收端返回 HTTP 4xx 或 5xx，本次通知会记录为发送失败。

安全限制

Webhook 地址必须是公开可访问的 HTTP 或 HTTPS URL。
内网地址、本机地址和云厂商元数据地址会被拒绝。
系统不会跟随跳转，建议直接填写最终接收地址。

请求示例

下面是一次站点异常通知的示例。实际字段会根据监控类型、当前状态和检测结果变化。

POST /your-webhook HTTP/1.1
Content-Type: application/json
X-GuGuJianKong-Signature: 4f8b7f...

{
  "event": "monitor.status_changed",
  "monitorType": "WEBSITE",
  "monitorId": "a78f0f2803174faa959ca8e0",
  "monitorTitle": "GuGuData Portal Website",
  "target": "https://www.gugudata.io",
  "status": -1,
  "previousStatus": 1,
  "checkedAt": "2026-06-12T21:25:37.153000",
  "responseTime": 2596.153,
  "failedNodes": ["杭州节点", "美国节点"],
  "message": "站点\"GuGuData Portal Website\"当前异常，异常节点：杭州节点、美国节点"
}

字段说明

字段	类型	说明
`event`	string	事件名称，目前为 `monitor.status_changed`，表示监控状态发生变化。
`monitorType`	string	监控类型，可能为 `WEBSITE`、`API`、`DEVICE`。
`monitorId`	string	监控对象 ID，可用于和你自己的系统做关联。
`monitorTitle`	string	监控对象名称。
`target`	string	监控目标地址，例如网站 URL、API URL 或设备 IP。
`status`	number	当前状态：`1` 正常，`0` 部分异常或待检测，`-1` 异常。
`previousStatus`	number	变化前状态，取值含义与 `status` 相同。
`checkedAt`	string	本次检测时间，使用 ISO 8601 字符串。
`responseTime`	number	本次检测响应时间，单位为毫秒。
`failedNodes`	array	异常节点名称列表。恢复通知时通常为空数组。
`message`	string	适合直接展示给值班人员的通知文案。

签名验证

如果你配置了签名密钥，咕咕监控会在请求头中发送 X-GuGuJianKong-Signature。签名值是使用密钥对原始 JSON 请求体计算的 HMAC-SHA256 十六进制字符串。

const crypto = require("crypto");

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

接收端验证签名时，请使用原始请求体参与计算，不要先格式化或重新序列化 JSON。签名密钥留空时，咕咕监控不会发送签名请求头。

如果你的系统需要接收监控异常、恢复和节点变化通知，可以在管理后台或移动端开启 Webhook 通知通道。

进入管理后台