Webhooks | XID

Abonnieren Sie implementierte Benutzer-, Organisations-, Mitgliedschafts-, Einladungs- und SAML-Zertifikatereignisse über signierte HTTP-Zustellungen.

Ereignisbenennung

Implementierte Ereignisse folgen dem Muster <object>.<action>. Der Header xid-webhook-event und der type im Body enthalten den exakten Ereignisnamen; jede Zustellung besitzt außerdem eine eindeutige svix-id.

Objekt	Aktionen
`user`	created, updated, deleted, restored, banned, unbanned, deactivated
`organization`	created, updated, deleted, restored
`organization.auth_policy`	aktualisiert
`organization.delivery_channels`	aktualisiert
`organization.social_providers`	aktualisiert
`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.*`	Abonnement-Wildcard für alle implementierten Benutzerereignisse.
`organization.*`	Subscription-Wildcard für alle implementierten Organisationsereignisse, einschließlich untergeordneter Ereignisse mit Punktnotation.
`organizationMembership.*`	Subscription-Wildcard für alle implementierten Organisationsmitgliedschaftsereignisse.
`*`	Abonnement-Wildcard für jedes implementierte Event.

Payload-Struktur

Jede Webhook-Zustellung ist ein HTTP POST mit Content-Type: application/json. Der Body enthält den exakten Ereignis-type und dessen data; die svix-Metadaten werden in den Request-Headern übertragen.

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

Signaturprüfung

XID signiert jede Zustellung mit HMAC-SHA256. Prüfen Sie die Signatur, bevor Sie die Nutzlast verarbeiten. Lehnen Sie Zustellungen ab, die älter als 5 Minuten sind, um Replay-Angriffe zu verhindern.

Kopfbereich	Beschreibung
`svix-id`	Eindeutige Nachrichten-ID. Verwenden Sie diese, um wiederholte Zustellungen zu deduplizieren.
`svix-timestamp`	Unix-Sekunden, als die Nachricht gesendet wurde.
`svix-signature`	Der svix-signature-Header beginnt mit dem wörtlichen v1-Präfix, gefolgt vom Base64-codierten HMAC-SHA256 von `${svix-id}.${svix-timestamp}.${raw-body}` unter Verwendung des Endpunktsignaturgeheimnisses.

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

Wiederholungen und unzustellbare Nachrichten

Zustellversuche verwenden exponentielles Backoff und enden im Status dead. Ist die Queue ausgeschöpft, wird die ursprüngliche Nachricht verschlüsselt als Dead-Letter-Eintrag gespeichert, damit ein Instance Manager sie prüfen und erneut zustellen kann.
Die Zustellung ist über Cloudflare Queues vom Authentifizierungspfad entkoppelt. Ein langsamer oder nicht verfügbarer Endpunkt beeinträchtigt die Anmelde-Latenz nicht.
Verwenden Sie den svix-id-Header, um Zustellungen auf Ihrer Seite zu deduplizieren. Wiederholungen tragen dieselbe svix-id wie der ursprüngliche Versuch.

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

Endpunktwiederherstellung

Verwenden Sie POST /v1/webhooks/:id/restore, um einen gelöschten Endpunkt zu reaktivieren, und POST /v1/webhooks/:id/rotate-secret, um sein Signaturgeheimnis zu ersetzen. Der neue signing_secret wird einmal zurückgegeben. Die Wiedergabe auf Produktebene nach Liefer-ID oder time range ist nicht implementiert.

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

Abgrenzung des Zustellverlaufs

XID stellt keine Pull Events API bereit. Verwenden Sie GET /v1/webhooks, um Subscriptions zu verwalten. Zustellstatus und erneute Zustellung aus der Dead-Letter-Queue sind Betriebsfunktionen für Instance Manager, kein Ereignisstrom für Mandanten.

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