审校于 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-timestamp | Unix 秒 |
x-publisher-signature | t=<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 密钥管理仍然可用。现有签名密钥绝不会再显示。