allybuildagent systems
登录注册

开发者文档 集成

Webhooks

项目内发生任务事件时收到 POST——完成、失败与审批关卡——载荷带签名，失败自动重试。

工作方式

在项目上注册 webhook：填入 URL、可选的签名密钥与关心的事件。匹配事件触发时，allybuild 会向你的 URL POST 一个 JSON 载荷。webhook 按项目生效：订阅了该事件的每个活跃 webhook 都会收到独立投递。

事件

事件触发时机
task_completed任务成功完成（含自动放行的运行）
task_failed任务出错
task_pending_approval任务停在审批关卡、等待人工处理

载荷

每次投递POST相同的信封。任务事件会内嵌任务记录：

{
  "id": "b6c7d8e9-...",
  "event": "task_completed",
  "project_id": "3f1c2b4a-...",
  "resource_type": "task",
  "resource_id": "9a2b8c7d-...",
  "title": "weekly report finished",
  "body": "",
  "timestamp": "2026-10-01T12:00:00.000Z",
  "task": {
    "id": "9a2b8c7d-...",
    "name": "weekly-report",
    "status": "success",
    "result": null,
    "error_message": null,
    "pr_url": null
  }
}

请求头与签名

请求头值
X-Webhook-Event事件类型，如 task_completed
X-Notification-Id载荷信封中的投递 id
X-Webhook-Signaturesha256=<hex>——用签名密钥对原始请求体做 HMAC-SHA256；配置了密钥才会发送

解析之前，先对原始请求体验签：

import crypto from "node:crypto";

app.post("/webhooks/allybuild", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  if (req.headers["x-webhook-signature"] !== expected) {
    return res.status(401).end();
  }

  const payload = JSON.parse(req.body.toString());
  // 按 payload.event 路由
  res.sendStatus(200);
});

可靠性

  • 每次尝试超时 10 秒；非 2xx 响应或网络错误都算失败
  • 失败投递最多重试 3 次，退避约 30s、60s、120s
  • 每次尝试都会记录：状态、HTTP 状态码、尝试次数与响应体摘录
  • 接受事件后尽快返回 2xx，重活异步处理