Webhook

所有者或管理员可以通过 /api/v1/webhooks 注册公开 HTTPS 地址，选择版本化事件、停用 Endpoint、轮换签名 Secret，并查看 Delivery。

Endpoint

GET, POST              /api/v1/webhooks
GET, PATCH, DELETE     /api/v1/webhooks/{webhookEndpointId}
POST                   /api/v1/webhooks/{webhookEndpointId}/rotate
POST                   /api/v1/webhooks/{webhookEndpointId}/test
GET                    /api/v1/webhooks/{webhookEndpointId}/deliveries
GET                    /api/v1/webhooks/{webhookEndpointId}/deliveries/{webhookDeliveryId}
POST                   /api/v1/webhooks/{webhookEndpointId}/deliveries/{webhookDeliveryId}/replay

读取需要 webhooks:read，生命周期操作需要 webhooks:write。创建和轮换只显示一次随机签名 Secret，之后只能读取脱敏信息。

目标必须是公开 HTTPS URL，不能包含凭据、Query、Fragment、自定义端口或本地/私网地址。

验证签名

每次 POST 包含稳定 Webhook-Id、Unix Webhook-Timestamp 和 Webhook-Signature。解析 JSON 前，使用 Secret 对 <id>.<timestamp>.<原始 Body> 计算 HMAC-SHA256，常量时间比较 v1= 值，并拒绝超过五分钟的时间戳。

Delivery 采用至少一次语义，接收方必须按稳定事件 ID 去重。网络或可重试 HTTP 错误使用有限指数退避；重定向会被拒绝。

测试与重放

控制台和 API 可以发送 webhook.test.v1，查看状态、延迟和尝试记录，并对仍在保留期内的失败 Delivery 安全重放一次。重放保留原事件 ID；已成功、处理中、过期、禁用或跨组织请求会被拒绝。

不要记录签名 Secret、Authorization Header 或不必要的完整客户 Payload。完整请求结构和事件 Enum 以 OpenAPI 为准。