Webhooks | XID

Suscríbase a eventos implementados de usuarios, organizaciones, membresías, invitaciones y certificados SAML a través de entregas HTTP firmadas.

Nomenclatura de eventos

Los eventos implementados siguen el patrón <object>.<action>. El header xid-webhook-event y el type del body contienen el nombre exacto del evento; cada entrega también tiene un svix-id único.

Objeto	Acciones
`user`	created, updated, deleted, restored, banned, unbanned, deactivated
`organization`	created, updated, deleted, restored
`organization.auth_policy`	actualizado
`organization.delivery_channels`	actualizado
`organization.social_providers`	actualizado
`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.*`	Comodín de suscripción para todos los eventos de usuario implementados.
`organization.*`	Comodín de suscripción para todos los eventos de la organización implementados, incluidos los subeventos punteados.
`organizationMembership.*`	Comodín de suscripción para todos los eventos de membresía de organizaciones implementados.
`*`	Comodín de suscripción para cada evento implementado.

Estructura del payload

Cada entrega de webhook es un HTTP POST con Content-Type: application/json. El cuerpo contiene el evento exacto type y su data; Los metadatos svix se incluyen en los encabezados de solicitud.

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

Verificación de firma

XID firma cada entrega con HMAC-SHA256. Verifica la firma antes de procesar el payload. Rechaza entregas con más de 5 minutos de antigüedad para prevenir ataques de reproducción.

Encabezado	Descripción
`svix-id`	ID de mensaje único. Úsalo para deduplicar entregas reintentadas.
`svix-timestamp`	Segundos Unix cuando se envió el mensaje.
`svix-signature`	El encabezado svix-signature comienza con el prefijo literal v1, seguido del HMAC-SHA256 codificado con Base64 de `${svix-id}.${svix-timestamp}.${raw-body}` utilizando el secreto de firma del punto final.

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

Reintentos y mensajes fallidos

Los intentos de entrega usan retroceso exponencial y terminan con el estado dead. Cuando se agota la cola, el mensaje original se conserva cifrado como registro no entregado para que un Instance Manager pueda inspeccionarlo y reenviarlo.
La entrega está desacoplada de la ruta de autenticación mediante Cloudflare Queues. Un endpoint lento o no disponible no afecta la latencia de inicio de sesión.
Usa el encabezado svix-id para deduplicar entregas en tu lado. Los reintentos llevan el mismo svix-id que el intento original.

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

Recuperación del endpoint

Utilice POST /v1/webhooks/:id/restore para reactivar un punto final eliminado y POST /v1/webhooks/:id/rotate-secret para reemplazar su secreto de firma. El nuevo signing_secret se devuelve una vez. La reproducción a nivel de producto por ID de entrega o time range no está implementada.

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

Límite del historial de entrega

XID no expone una Events API de consulta. Usa GET /v1/webhooks para gestionar las suscripciones. El estado de entrega y el reenvío desde la cola de mensajes no entregados son superficies operativas para Instance Managers, no un flujo de eventos del tenant.

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