Webhook 回调

POST https://api.beatapi.io/v1/webhooks

创建 Webhook 端点，按需接收 BeatAPI 任务完成回调。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。请按当前接口文档处理重试，不要对结果不明的创建请求盲目重发。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

url   string   必填

接收 BeatAPI 任务事件的公网 HTTPS 回调 URL。

取值与默认值: 格式 uri

description   string   选填

用于说明对象、主体或端点用途的文字。

events   string[]   选填

该 Webhook 端点要订阅的事件列表。

取值与默认值: 可选值 task.succeeded、task.failed

响应

成功请求返回 HTTP 201，响应体如下。

1
{
2
  "data": {
3
    "id": "wh_9aBcD",
4
    "object": "webhook_endpoint",
5
    "url": "https://example.com/beatapi-webhook",
6
    "description": "Production webhook",
7
    "events": [
8
      "task.succeeded",
9
      "task.failed"
10
    ],
11
    "status": "active",
12
    "secret": "whsec_example_store_this_once",
13
    "created_at": 1782210000,
14
    "updated_at": 1782210000
15
  }
16
}

验证回调签名

BeatAPI 每次投递都会发送 x-beatapi-event、x-beatapi-timestamp 和 x-beatapi-signature。请对下面的内容计算十六进制 HMAC-SHA256。

timestamp + "." + raw_request_body

使用创建端点时返回的 secret。必须在 JSON 解析前按原始字节计算签名，使用常量时间比较，并拒绝超过 5 分钟的时间戳。

管理端点

• GET /v1/webhooks：列出 Webhook 端点。
• GET /v1/webhooks/{id}：查询 Webhook 端点。
• PATCH /v1/webhooks/{id}：更新 Webhook 端点。
• DELETE /v1/webhooks/{id}：删除 Webhook 端点。

下一步

解析回调数据前验证签名。投递延迟或失败时，GET /v1/tasks/{task_id} 的查询结果仍然是任务状态真源。

错误