跳到主要内容

测试 Webhook

向某个 Webhook 发送一个合成事件，用于验证连通性、TLS 与签名处理。该事件由 PipAI 生成，并通过正常的投递管线送达——使用相同的请求头、相同的签名、相同的重试语义——因此一次成功的测试可以确认你的处理逻辑端到端连接正确。

端点​

POST /v1/webhooks/{id}/test

权重： 10 鉴权： 必须（已签名）——参见 鉴权。

该端点是同步的：请求会阻塞直到合成投递完成或超时（10 秒）。请节制使用——它的权重比其他 Webhook 端点更高，因为它会占用一个投递槽位。

路径参数​

名称类型必填说明
idstringYESWebhook 标识，格式为 wh_<6-8 hex>。

请求体​

名称类型必填说明
event_typestringNO嵌入到合成事件请求体中的 type 字段。默认为 webhook.test。允许传入真实的事件类型（例如 strategy.deployed）——data 负载将填入虚拟值。

响应​

{
  "test_event_id": "evt_test_b7f2c1a93d",
  "delivered": true,
  "response_status": 200,
  "response_time_ms": 187,
  "error": null
}

投递失败时：

{
  "test_event_id": "evt_test_b7f2c1a93d",
  "delivered": false,
  "response_status": 502,
  "response_time_ms": 412,
  "error": "Endpoint returned non-2xx status"
}

响应字段​

字段类型说明
test_event_idstring合成事件的标识，格式为 evt_test_<10-12 hex>。测试事件 ID 使用 evt_test_ 前缀，便于在生产监控数据中过滤掉。
deliveredboolean当端点在 10 秒超时内返回 2xx 状态时为 true，否则为 false。
response_statusinteger|null端点返回的 HTTP 状态；若端点未响应（TLS 错误、连接被拒、超时）则为 null。
response_time_msinteger|null从请求发出到收到响应的实际耗时（毫秒）。若未收到响应则为 null。
errorstring|null失败时的人类可读错误描述；成功时为 null。

成功的测试（delivered: true）会将该 Webhook 的 consecutive_failures 计数器重置为 0，这是恢复一个尚未触及自动暂停阈值但已积累失败的 active Webhook 的官方方式。

错误​

  • 403 INSUFFICIENT_PERMISSION —— API 密钥缺少 webhooks:write 范围。
  • 404 NOT_FOUND —— 该账户上不存在该 id 对应的 Webhook。
  • 409 INVALID_STATE —— 该 Webhook 的 status 为 broken。失效（broken）的 Webhook 必须先通过仪表盘或（即将推出的）PATCH 端点重新激活，才能发送测试。这可以避免对已经连续失败 50 次的端点产生意外流量。

请注意，投递失败（例如端点返回 5xx）不是 请求级错误——API 调用本身会返回 200 OK，请求体中 delivered: false。只有元数据级别的问题才会产生非 200 响应。

完整列表参见 错误。

示例​

curl -X POST "https://api.pipai.example/v1/webhooks/wh_2a4f10/test" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "strategy.deployed"
  }'