AiVideoEditor
免费开始
菜单

审校于 2026-11-11 · API 版本 2026-11-09 · 阅读 Markdown

客户 webhook

面向你工作区的出站事件交付。注册一个 HTTPS 端点,验证一次性签名密钥,并以有界重试接收已签名的事件。

注册端点

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • 签名密钥(whsec_…)仅返回一次:在第一次成功创建的响应中。请存储它;同一创建的幂等重放会返回不含密钥的端点,且它无法再次显示。
  • 目标必须是 HTTPS、可公开解析,且不含嵌入凭据。对私有、回环、链路本地(包括云元数据)、唯一本地和多播地址的请求在任何连接建立之前就会被拒绝,并且重定向从不被跟随。
  • 注册会为该端点入队一个定向的 webhook.verification 事件,独立于其 eventTypes 过滤器。只有当你的端点以 2xx 回应验证后,普通事件才会流动。

验证交付

每个请求都带有:

请求头含义
x-publisher-event-id稳定的事件 ID:在重试和重放中保持一致
x-publisher-event-type事件类型,例如 post.published
x-publisher-timestampUnix 秒
x-publisher-signaturet=<ts>,v1=<hex>

签名是使用你的签名密钥对 ${t}.${event_id}.${raw_body} 计算的 HMAC-SHA256。以 ±300 秒的容差验证,并拒绝超出容差的重放。Node 示例:

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

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

始终在解析之前针对原始请求体验证。

事件信封

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

初始事件目录(可扩展;注册时 eventTypes 过滤):

  • webhook.verification:挑战载荷;以 2xx 回应以激活端点
  • post.published:一个目标已确认并带有原生回执
  • delivery.failed:一个目标终态失败
  • delivery.requires_action:需要同意/重新连接/延迟审查

聚合帖子结果(post.partially_published、post.failed)尚未发出;只有在存在生产者之后才会在此记录,因此不要依赖它们。订阅上述按目标的事件,并从帖子的交付结果推导批次状态。

重试、重放与禁用

  • 尝试时机:立即,然后 +1m、+5m、+30m、+2h、+8h。重试复用相同的事件 ID 和字节一致的请求体,因此你可以安全地去重。
  • 2xx = 已交付。429/5xx/超时会重试。其他 4xx 对该事件永久失败(修复端点,然后重放)。
  • 410 Gone 禁用端点:不再向其入队任何事件。
  • 经操作员授权的重放通过内部 webhook 服务以其原始 ID 重新发送事件。处于活跃租约中的进行中尝试绝不会被中断;重放会报告该事件正忙,稍后可重试。

运营说明

  • 交付诊断只存储安全的结果代码:绝不会存储你的机密、签名、请求头或响应体。载荷还会被清理:在任何内容入队之前,提供方/OAuth 机密和媒体预签名 URL 会被剥离。
  • 端点是工作区范围的:持有来自其他工作区的端点 UUID 没有任何作用。
  • 每个已接受的事件发生至少交付一次;在 x-publisher-event-id 上去重。

开发者工具可用性

Developers 页面独立于签名密钥加密配置,列出工作区 API 密钥和 webhook 端点。创建 webhook 需要有效的服务器加密配置;请让部署操作员解决配置警告。API 密钥管理仍然可用。现有签名密钥绝不会再显示。