# Webhook 与集成

将治理事件推送到您自己的工具，并在 Slack 或 Microsoft Teams 中对 Azoth 进行操作。

## 治理 Webhook

在**设置 › 集成与告警 › Webhook** 中添加一个 HTTPS 端点（GRC 或 ITSM 工具、SIEM），然后勾选它要接收的事件：

- `decision.blocked` — 一项决策以阻止结果被封存
- `derogation` — 一项策略豁免、红队豁免或法律解读被申请、批准、拒绝或撤销
- `proof.broken` — 每小时的验证发现工作区的链已断裂

> 仅含 ID、代码和哈希：不含内容、姓名或自由文本。需要更多信息的接收方可以使用自己的密钥查询 API（`GET /api/v1/journal`）。

```
{
  "id": "<delivery uuid>",
  "event": "decision.blocked",
  "workspace_id": "<workspace>",
  "created_at": "<iso date>",
  "data": { "seq": 1042, "entryHash": "<sha256>", "decision": "blocked_by_policy", "traceId": "…" }
}
```

## 验证签名

每次投递都附带 `X-Azoth-Event`、`X-Azoth-Delivery`（重试时保持不变，请据此去重）、`X-Azoth-Timestamp` 和 `X-Azoth-Signature: t=<timestamp>,v1=<hex>`，后者是使用端点签名密钥对 `<timestamp>.<raw body>` 计算的 HMAC-SHA256。

```
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAzothWebhook(rawBody, header, secret, toleranceSecs = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.floor(Date.now() / 1000) - t > toleranceSecs) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(parts.v1, 'hex'), b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

// In a route handler: read the RAW body before parsing it.
export async function POST(req) {
  const body = await req.text();
  if (!verifyAzothWebhook(body, req.headers.get('x-azoth-signature') ?? '', process.env.AZOTH_WEBHOOK_SECRET)) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }
  const event = JSON.parse(body);   // deduplicate on event.id (= X-Azoth-Delivery)
  return Response.json({ ok: true });
}
```

决策先被封存。投递失败会以退避方式重试，最多五次；在投递前被移除的端点会丢弃其待处理事件。

## Slack

- 使用 `/azoth <question>` 或私信向 Azoth 提问：与应用内助手使用同一引擎，并使用您的身份和角色。回答只发送给您，绝不发送到频道。
- 通过 MFA 关联的所有者和管理员会收到等待其处理的审批和豁免，并一键做出决定——角色在点击时读取，强制执行四眼原则，决定会被封存。角色变更、保留期变更或红队豁免始终在 Azoth 中打开。
- 使用 `/azoth link` 关联您的账户。

## Microsoft Teams 机器人

- 每个组织注册自己的单租户机器人。其密钥会加密保存，并在保存前经 Microsoft 校验，Azoth 会为其构建应用包。
- 您在与机器人的一对一聊天中提出的问题会以您的身份作答；审批和豁免会以卡片形式发送给通过 MFA 关联的所有者和管理员，并按与 Slack 相同的规则做出决定。

## PagerDuty 与告警渠道

工作区的每条告警（待决定的审批、治理、登录异常、提供商故障、模型变更、已停止的智能体循环、密封决策配额）都会发送到**设置 › 集成与告警 › 告警**中的告警路由：PagerDuty（去重）、Slack 或 Teams 频道 Webhook，或电子邮件，每条路由从其设定的最低严重级别起接收。预算阈值告警发送到每个预算各自设置的目标。

## GitHub App 集成

- 从**设置 › 集成与告警**安装 GitHub App 并选择其仓库：已启用仓库上的每个拉取请求都会获得一个检查运行。关联了回归测试套件的仓库会获得每个用例的结果；套件通过 API（`POST /api/v1/regression/suites`）创建，目前还没有界面可以关联套件——若想现在就测试拉取请求，请在 CI 中用 [CLI](https://www.azothos.ai/zh/docs/cli#ci) 运行套件。
- 为某个仓库开启读取后，同一个 App 会读取该仓库的 AI 足迹（[增强功能](https://www.azothos.ai/zh/docs/enrichments#footprint)）。
