---
title: "Webhooks"
description: "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."
locale: "fr"
---

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

# Webhooks

## Nommage des événements

Les événements implémentés suivent le modèle `<object>.<action>`. Le header vonvon-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.

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

## Vérification de signature

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

```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
```

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

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

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

## Limite de l'historique de livraison

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

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

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