ZeeDo API

在“设置 → API 与 Webhook”中创建密钥（所有者需先确认身份），然后将它作为 Bearer 令牌调用 API。基础 URL 为 https://api.zeedo.cloud/v1。

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <您的 API 密钥>"

• 密钥属于组织，带有一个权限范围（read、write 或 admin），并可限定于一个工作区。
• JSON 请求体，字段采用 snake_case，时间采用 ISO 8601 UTC 格式。
• 错误为 RFC 9457 问题文档：type、title、status、detail；字段被拒绝时，还有带 JSON 指针的 errors[]。
• 列表通过 limit（最多 200）和 next_cursor 分页。
• 每个 POST 请求都请带上 Idempotency-Key 请求头：24 小时内的重复请求会返回首次请求的结果。
• 每个密钥每分钟 600 个请求、10 个打开的流，并返回 RateLimit-* 请求头。

一个组织注册一个端点（“设置 → API 与 Webhook”，或 POST /webhooks）并选择事件。每个事件都是一个 JSON 格式的 POST 请求，包含 ID、类型和时间戳，绝不包含个人的姓名、电子邮件或 IP 地址；这些信息请用密钥通过 API 读取。

{
  "id": "evt_eu_01J9ZQ3M7X5V2K8R4T6Y1N0PBA",
  "type": "run.completed",
  "version": 1,
  "occurred_at": "2026-09-27T10:02:31.000Z",
  "org_id": "org_eu_01J9ZQ1C4H8D6F2W5S7K3M9QXE",
  "data": {
    "run_id": "run_eu_01J9ZQ2V8N4B6C1X3Z5Q7W9ERT",
    "bot_id": "bot_eu_01J9ZQ2A3S5D7F9G1H3J5K7L9M"
  }
}

每次推送都带有签名：ZeeDo-Signature: t=<Unix 秒>,v1=<签名>，其中签名是以您端点的密钥对 <t>.<原始请求体> 计算的十六进制 HMAC-SHA256。轮换密钥后，旧密钥会在 24 小时内同时签名，作为第二个 v1。请拒绝超过 5 分钟的签名。

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

// header：ZeeDo-Signature 的值；body：原始请求体，在任何 JSON 解析之前
export function verified(header, body, secret) {
  const parts = header.split(',');
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return parts.filter((p) => p.startsWith('v1=')).some((p) =>
    p.length === expected.length + 3 && timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
}

• 请在 10 秒内返回任意 2xx 响应。其他任何情况（错误、重定向、无响应）都会在 24 小时内以递增的间隔重试；之后该推送成为死信，保留 7 天，可在“设置”中重新发送。
• 推送至少送达一次，且不保证顺序：请跳过已处理过的 id。
• 请求还带有 ZeeDo-Event-Id、ZeeDo-Event-Type 和 ZeeDo-Delivery-Id。端点须为公共主机名上 443 端口的 https 地址。
• 事件：alert.fired、approval.decided、approval.requested、billing.service_state_changed、bot.state_changed、budget.threshold、connection.created、connection.error、consent.recorded、memory.note_created、policy.updated、run.cancelled、run.completed、run.failed、run.parked、task.completed和task.created。
• 要检查您的端点，请在“设置 → API 与 Webhook”中按“发送测试”：系统会发送一次类型为 webhook.test、data 为空的推送，签名方式与其他推送相同，无论您选择了哪些事件都会发送。每分钟最多一次。