Webhook | XID

서명된 HTTP 전달을 통해 구현된 사용자, 조직, 멤버십, 초대 및 SAML 인증서 이벤트를 구독합니다.

이벤트 명명 규칙

구현된 이벤트는 <object>.<action> 패턴을 따릅니다. xid-webhook-event 헤더와 본문 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.*`	구현된 모든 조직 멤버십 이벤트에 대한 구독 와일드카드입니다.
`*`	구현된 모든 이벤트에 대한 구독 와일드카드입니다.

페이로드 구조

모든 웹훅 전달은 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-letter

전달은 지수 백오프로 재시도되며 최종적으로 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는 pull 방식의 Events API를 제공하지 않습니다. GET /v1/webhooks로 구독을 관리하세요. 전달 상태와 큐 데드 레터 재처리는 Instance Manager를 위한 운영 화면이며 테넌트 이벤트 스트림이 아닙니다.

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