Webhooks | XID

Abonnez-vous aux événements d'utilisateur, d'organisation, d'adhésion, d'invitation et de certificat SAML implémentés via des diffusions HTTP signées.

Nommage des événements

Les événements implémentés suivent le modèle <object>.<action>. Le header xid-webhook-event et le type du body contiennent le nom exact de l’événement; chaque livraison possède également un svix-id unique.

Objet	Opérations
`user`	created, updated, deleted, restored, banned, unbanned, deactivated
`organization`	created, updated, deleted, restored
`organization.auth_policy`	mis à jour
`organization.delivery_channels`	mis à jour
`organization.social_providers`	mis à jour
`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.*`	Caractère générique d’abonnement pour tous les événements utilisateur implémentés.
`organization.*`	Caractère générique d’abonnement pour tous les événements d’organisation implémentés, y compris les sous-événements en pointillés.
`organizationMembership.*`	Caractère générique d’abonnement pour tous les événements d’adhésion à l’organisation implémentés.
`*`	Caractère générique d’abonnement pour chaque événement implémenté.

Structure du payload

Chaque livraison de webhook est un HTTP POST avec Content-Type: application/json. Le corps contient l’événement exact type et son data ; Les métadonnées svix sont contenues dans les en-têtes de requête.

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

Vérification de signature

XID signe chaque livraison avec HMAC-SHA256. Vérifiez la signature avant de traiter le payload. Rejetez les livraisons de plus de 5 minutes pour prévenir les attaques par rejeu.

En-tête	Description
`svix-id`	Identifiant unique du message. Utilisez-le pour dédupliquer les livraisons relancées.
`svix-timestamp`	Secondes Unix indiquant quand le message a été envoyé.
`svix-signature`	L’en-tête svix-signature commence par le préfixe littéral v1, suivi du HMAC-SHA256 codé en Base64 de `${svix-id}.${svix-timestamp}.${raw-body}` à l’aide du secret de signature du point de terminaison.

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

Relances et dead letters

Les tentatives de livraison utilisent un backoff exponentiel et se terminent avec le statut dead. Lorsque la file est épuisée, le message d’origine est conservé sous forme chiffrée afin qu’un Instance Manager puisse l’inspecter et le renvoyer.
La livraison est découplée du chemin d’authentification via les Cloudflare Queues. Un endpoint lent ou indisponible n’affecte pas la latence de connexion.
Utilisez l’en-tête svix-id pour dédupliquer les livraisons de votre côté. Les relances portent le même svix-id que la tentative d’origine.

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

Récupération de point de terminaison

Utilisez POST /v1/webhooks/:id/restore pour réactiver un point de terminaison supprimé et POST /v1/webhooks/:id/rotate-secret pour remplacer son secret de signature. Le nouveau signing_secret est renvoyé une fois. La relecture au niveau du produit par ID de livraison ou time range n’est pas implémentée.

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

Limite de l’historique de livraison

XID n’expose pas d’Events API de consultation. Utilisez GET /v1/webhooks pour gérer les abonnements. L’état des livraisons et le renvoi depuis la file des messages non distribués sont des surfaces opérationnelles pour les Instance Managers, et non un flux d’événements du tenant.

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