---
title: "Webhooks"
description: "Abonnieren Sie implementierte Benutzer-, Organisations-, Mitgliedschafts-, Einladungs- und SAML-Zertifikatereignisse über signierte HTTP-Zustellungen."
locale: "de"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/de/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

## Ereignisbenennung

Implementierte Ereignisse folgen dem Muster `<object>.<action>`. Der Header vonvon-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.

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

## Signaturprüfung

Vonvon 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. |

```ts
import { verifyWebhook } from '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_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.

```mermaid
flowchart LR
  Vonvon --> 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.

```shell
curl -X POST https://vonvon.id/v1/webhooks/webhook_xxx/rotate-secret \
  -H 'Authorization: Bearer sk_live_xxx'
```

## Abgrenzung des Zustellverlaufs

Vonvon 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.

```shell
curl 'https://vonvon.id/v1/webhooks?limit=100' \
  -H 'Authorization: Bearer sk_live_xxx'
```

Source: https://vonvon.id/de/webhooks/index.mdx