Webhooks | XID

Assine eventos implementados de usuário, organização, associação, convite e certificado SAML por meio de entregas HTTP assinadas.

Nomenclatura de eventos

Os eventos implementados seguem o padrão <object>.<action>. O header xid-webhook-event e o type do body contêm o nome exato do evento; cada entrega também tem um svix-id exclusivo.

Objeto	Ações
`user`	created, updated, deleted, restored, banned, unbanned, deactivated
`organization`	created, updated, deleted, restored
`organization.auth_policy`	atualizado
`organization.delivery_channels`	atualizado
`organization.social_providers`	atualizado
`organization.outbound_saml_app`	created, deleted
`organization.scim_target`	created, deleted
`organizationMembership`	created, updated, deleted, restored
`organizationInvitation`	created, accepted, revoked
`connection`	saml_certificate_renewed
`user.*`	Curinga de assinatura para todos os eventos de usuário implementados.
`organization.*`	Curinga de assinatura para todos os eventos da organização implementados, incluindo subeventos pontilhados.
`organizationMembership.*`	Curinga de assinatura para todos os eventos de associação da organização implementados.
`*`	Curinga de assinatura para cada evento implementado.

Estrutura do payload

Cada entrega de webhook é um HTTP POST com Content-Type: application/json. O corpo contém o evento exato type e seu data; Os metadados svix são transportados em cabeçalhos de solicitação.

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

Verificação de assinatura

O XID assina cada entrega com HMAC-SHA256. Verifique a assinatura antes de processar o payload. Rejeite entregas com mais de 5 minutos para evitar ataques de replay.

Cabeçalho	Descrição
`svix-id`	ID de mensagem único. Use para deduplicar entregas repetidas.
`svix-timestamp`	Segundos Unix em que a mensagem foi enviada.
`svix-signature`	O cabeçalho svix-signature começa com o prefixo literal v1, seguido pelo HMAC-SHA256 codificado em Base64 de `${svix-id}.${svix-timestamp}.${raw-body}` usando o segredo de assinatura do terminal.

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

Tentativas e dead letters

As tentativas de entrega usam backoff exponencial e terminam com o status dead. Quando a fila se esgota, a mensagem original é armazenada de forma criptografada para que um Instance Manager possa inspecioná-la e reenviá-la.
A entrega é desacoplada do caminho de autenticação via Cloudflare Queues. Um endpoint lento ou indisponível não afeta a latência de login.
Use o cabeçalho svix-id para deduplicar entregas no seu lado. As tentativas carregam o mesmo svix-id da tentativa original.

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

Recuperação de endpoint

Use POST /v1/webhooks/:id/restore para reativar um endpoint excluído e POST /v1/webhooks/:id/rotate-secret para substituir seu segredo de assinatura. O novo signing_secret é retornado uma vez. A reprodução no nível do produto por ID de entrega ou time range não está implementada.

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

Limite do histórico de entrega

O XID não expõe uma Events API de consulta. Use GET /v1/webhooks para gerenciar assinaturas. O estado das entregas e o reenvio da fila de mensagens não entregues são superfícies operacionais para Instance Managers, não um fluxo de eventos do tenant.

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