出站事件 Webhook

本页介绍出站事件 Webhook：Almirant 会将项目事件通知发送到你的服务器。如需从外部系统启动智能体，请使用智能体 Webhook。

当项目中发生事件时，Almirant 会向你的服务器发送出站 HTTP 通知。每当创建工作项、在列之间移动工作项或关闭冲刺时，Almirant 都会向你配置的 URL 发送 POST 请求。

它可用于：

• 将 Almirant 与外部工具同步（Slack、Discord 或你的自有仪表板）
• 在任务状态变更时触发 CI/CD 流水线
• 向分析或报告系统提供数据
• 自动执行 Almirant 外部的自定义工作流

创建 Webhook

1. 在项目中前往 设置 > Webhook
2. 点击 创建 Webhook
3. 填写字段：

字段	说明	示例
URL	将接收通知的 HTTPS 端点	https://my-server.com/webhooks/almirant
事件	触发 Webhook 的事件类型	work_item.created、sprint.closed
密钥	用于验证请求真实性的密钥	自动生成，或由你自行定义

4. 点击 保存

重要

URL 必须可从互联网访问且使用 HTTPS。Almirant 不会向未加密的 HTTP URL 发送 Webhook（开发环境中的 localhost 除外）。

可用事件

创建 Webhook 时选择一个或多个事件：

事件	触发条件
work_item.created	创建了新的工作项
work_item.updated	工作项字段已修改（标题、说明、优先级等）
work_item.moved	工作项在看板列之间移动
work_item.archived	工作项已归档
lead.created	在 CRM 中创建了新的潜在客户
lead.updated	潜在客户数据已更新
lead.stage_changed	潜在客户在漏斗中变更阶段
sprint.created	创建了新的冲刺
sprint.closed	冲刺已关闭

提示

如果你只需要响应看板变更，请仅选择 work_item.* 事件。订阅的事件越少，服务器收到的流量越少。

验证 Webhook 签名

每个请求都会在 X-Almirant-Signature 请求头中包含 HMAC-SHA256 签名，使你能够验证请求确实来自 Almirant 且未被篡改。

验证方式

1. Almirant 使用你的 密钥 对请求正文生成 HMAC-SHA256 哈希
2. 它将该哈希包含在 X-Almirant-Signature 请求头中
3. 你的服务器使用相同的密钥重新计算哈希并进行比较

Node.js 示例

import crypto from 'node:crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// 在你的端点中：
app.post('/webhooks/almirant', (req, res) => {
  const signature = req.headers['x-almirant-signature'];
  const rawBody = req.rawBody; // 请求正文为字符串，未经解析

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody);
  console.log('Event received:', event.type);

  // 处理事件...

  res.status(200).json({ received: true });
});

Python 示例

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

安全性

在处理事件前务必验证签名。未验证真实性时，绝不应信任 Webhook 数据。使用 timingSafeEqual（或等效方法）防止时序攻击。

查看投递日志

每个 Webhook 都会保留可供检查的投递历史记录，以便调试问题。

1. 前往 设置 > Webhook
2. 点击要检查的 Webhook
3. 在 投递 标签页中，你会看到包含以下内容的列表：

列	说明
日期	投递的准确时间
事件	触发投递的事件类型
状态	HTTP 响应代码（200、500、超时等）
时长	服务器的响应时间

点击任意投递即可查看完整详情：发送的请求头、负载正文和服务器响应。

重试和失败

Almirant 会使用指数退避自动重试失败的投递：

尝试次数	重试前等待时间
1	立即
2	1 分钟
3	5 分钟
4	30 分钟
5	2 小时

在以下情况下，投递会被视为失败：

• 你的服务器返回 HTTP 状态码 >= 400
• 你的服务器未在 10 秒内响应（超时）
• 无法建立到你的服务器的连接

失败 5 次后，投递将被标记为失败，且不再重试。你可以从投递日志中手动重新发送。

注意

你的服务器应尽快返回 HTTP 2xx 状态码（最好是 200）。如果需要进行耗时处理，请立即接受 Webhook，然后异步处理数据。

禁用或删除 Webhook

• 禁用：在 Webhook 列表中，使用开关暂时禁用它。投递会暂停，但配置会保留。
• 删除：点击删除图标。此操作不可逆，并且会删除投递历史记录。