Webhooks | XID

通过签名的 HTTP 交付订阅已实施的用户、组织、成员资格、邀请和 SAML 证书事件。

事件命名

已实现的事件遵循 <object>.<action> 模式。xid-webhook-event header 和正文 type 携带准确的事件名称；每次投递还具有唯一的 svix-id。

对象	操作
`user`	已创建、已更新、已删除、已恢复、已封禁、已解封、已停用
`organization`	已创建、已更新、已删除、已恢复
`organization.auth_policy`	已更新
`organization.delivery_channels`	已更新
`organization.social_providers`	已更新
`organization.outbound_saml_app`	已创建、已删除
`organization.scim_target`	已创建、已删除
`organizationMembership`	已创建、已更新、已删除、已恢复
`organizationInvitation`	created, accepted, revoked
`connection`	saml_certificate_renewed
`user.*`	所有已实现的用户事件的订阅通配符。
`organization.*`	用于订阅所有已实现组织事件的通配符，包括点分子事件。
`organizationMembership.*`	用于订阅所有已实现组织成员关系事件的通配符。
`*`	每个已实施事件的订阅通配符。

payload 结构

每次 Webhook 投递都是带有 Content-Type: application/json 的 HTTP POST。正文包含准确的事件 type 及其 data；svix 元数据通过请求 header 传递。

{
  "type": "user.created",
  "data": {
    "userId": "user_01abc"
  }
}

签名验证

XID 对每次投递使用 HMAC-SHA256 签名。在处理 payload 前请先验证签名。拒绝 5 分钟前的投递以防重放攻击。

请求头	描述
`svix-id`	唯一消息 ID。用于对重试投递去重。
`svix-timestamp`	消息发送时的 Unix 时间戳（秒）。
`svix-signature`	svix-signature header 以字面量前缀 v1, 开头，随后是使用端点签名 secret 对 `${svix-id}.${svix-timestamp}.${raw-body}` 计算得到的 Base64 编码 HMAC-SHA256。

import { verifyWebhook } from '@xid-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.XID_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload

重试与死信

投递使用指数退避重试，最终进入 dead 状态。队列重试耗尽后，原始消息会作为加密死信记录持久化，供 Instance Manager 检查和重放。
交付通过 Cloudflare Queues 与认证路径解耦。端点缓慢或不可用不会影响登录延迟。
使用 svix-id 请求头在接收端去重。重试的投递与原始尝试携带相同的 svix-id。

flowchart LR
  XID --> Queue
  Queue -->|HTTPS| Endpoint
  Endpoint -->|2xx| ACK
  Endpoint -->|non-2xx| Retry
  Retry --> Queue
  Retry -->|max_retries| dlq["D1 DLQ"]

端点恢复

使用 POST /v1/webhooks/:id/restore 重新激活已删除的端点，使用 POST /v1/webhooks/:id/rotate-secret 替换其签名 secret。新的 signing_secret 仅返回一次。尚未实现按投递 ID 或时间范围进行产品级重放。

curl -X POST https://xid.dev/v1/webhooks/webhook_xxx/rotate-secret \
  -H 'Authorization: Bearer sk_live_xxx'

投递历史边界

XID 不提供拉取式 Events API。使用 GET /v1/webhooks 管理订阅；投递状态和队列死信重放是供 Instance Manager 使用的运维界面，不是租户事件流。

curl 'https://xid.dev/v1/webhooks?limit=100' \
  -H 'Authorization: Bearer sk_live_xxx'