webhook | XID

署名された HTTP 配信を通じて、実装されたユーザー、組織、メンバーシップ、招待、および SAML 証明書イベントをサブスクライブします。

イベント命名規則

実装されたイベントは、<object>.<action> のパターンに従います。 xid-webhook-event ヘッダーと本体タイプには正確なイベント名が含まれます。すべての配信には一意の 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.*`	ドット区切りのサブイベントを含む、実装済みの全 Organization イベントを購読するワイルドカード。
`organizationMembership.*`	実装されたすべての組織メンバーシップイベントのサブスクリプションワイルドカード。
`*`	実装されたすべてのイベントのサブスクリプションワイルドカード。

ペイロード構造

すべての Webhook 配信は、Content-Type: application/json の HTTP POST です。本文には、正確なイベントのタイプとそのデータが含まれています。 svix メタデータはリクエストヘッダーに含まれます。

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

署名検証

XID はすべての配信を HMAC-SHA256 で署名します。ペイロードを処理する前に署名を検証してください。リプレイ攻撃を防ぐため、5 分以上経過した配信は拒否してください。

ヘッダー	説明
`svix-id`	一意のメッセージ ID。再試行された配信の重複排除に使用してください。
`svix-timestamp`	メッセージが送信された時刻（Unix 秒）。
`svix-signature`	svix-signature ヘッダーはリテラルの v1 プレフィックスで始まり、エンドポイント署名シークレットを使用する `${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 で署名シークレットを置き換えます。新しい 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'