# Webhooks

Ajoutez `webhooks` à une table pour déclencher des requêtes HTTP `POST` sortantes lorsque des enregistrements sont créés, mis à jour ou supprimés. Chaque webhook est du sucre syntaxique au-dessus des automatisations — en interne, il se déploie en un déclencheur d'enregistrement plus une action `webhook.send`. Les noms de webhooks doivent être uniques au sein de la table.

## Propriétés des webhooks

| Propriété | Description                                                                                                                |
| --------- | -------------------------------------------------------------------------------------------------------------------------- |
| `name`    | **Requis.** Identifiant unique du webhook au sein de la table.                                                             |
| `url`     | **Requis.** URL de destination. Doit être une URL `http(s)` absolue valide.                                                |
| `events`  | **Requis.** Événements d'enregistrement qui déclenchent la livraison : l'un de `create`, `update`, `delete` (au moins un). |
| `enabled` | Booléen. Indique si le webhook est actif (par défaut `true`).                                                              |
| `auth`    | Authentification de la requête sortante (HMAC, clé API ou bearer). Voir ci-dessous.                                        |
| `retry`   | Politique de réessai pour les livraisons échouées. Voir ci-dessous.                                                        |
| `payload` | Sélection des champs du payload et options de métadonnées. Voir ci-dessous.                                                |

```yaml
webhooks:
  - name: order_created
    url: https://hooks.example.com/orders
    events: [create]
    enabled: true
```

## Authentification

`auth` sécurise la requête. Trois types sont pris en charge ; les secrets/clés/jetons prennent en charge les références `$env.`.

| Type     | Propriétés                                                                                                 |
| -------- | ---------------------------------------------------------------------------------------------------------- |
| `hmac`   | `secret` (requis), `algorithm` (`sha256` par défaut, ou `sha1`), `header` (nom de l'en-tête de signature). |
| `apiKey` | `key` (requis), `header` (nom de l'en-tête portant la clé).                                                |
| `bearer` | `token` (requis) envoyé en tant que jeton bearer.                                                          |

```yaml
auth: { type: hmac, secret: '$env.PARTNER_WEBHOOK_SECRET', algorithm: sha256 }
```

```yaml
auth: { type: apiKey, key: '$env.SERVICE_API_KEY', header: X-API-Key }
```

```yaml
auth: { type: bearer, token: '$env.API_BEARER_TOKEN' }
```

## Politique de réessai

`retry` contrôle la façon dont les livraisons échouées sont réessayées.

| Propriété      | Description                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `maxAttempts`  | Nombre de tentatives de réessai après l'échec initial. `0` désactive les réessais. Par défaut `3`. |
| `backoff`      | Stratégie de backoff : `exponential` ou `fixed`.                                                   |
| `initialDelay` | Millisecondes avant le premier réessai (par défaut `1000`).                                        |
| `maxDelay`     | Délai maximal en millisecondes entre les réessais.                                                 |

```yaml
retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
```

## Sélection du payload

`payload` façonne les données envoyées. `includeFields` (liste blanche) et `excludeFields` (liste noire) sont mutuellement exclusifs, et chaque champ nommé doit exister sur la table (l'`id` implicite est toujours valide).

| Propriété               | Description                                                                      |
| ----------------------- | -------------------------------------------------------------------------------- |
| `includeFields`         | N'inclut que ces champs (liste blanche).                                         |
| `excludeFields`         | Exclut ces champs (liste noire).                                                 |
| `includePreviousValues` | Inclut les valeurs précédentes de l'enregistrement lors des événements `update`. |
| `includeMetadata`       | Inclut les métadonnées de l'événement dans le payload.                           |

```yaml
payload: { includeFields: [customer, status, total], includePreviousValues: true }
```

## Exemple complet

```yaml
webhooks:
  - name: order_lifecycle
    url: https://hooks.example.com/orders
    events: [create, update, delete]
    enabled: true
    auth: { type: hmac, secret: '$env.ORDER_WEBHOOK_SECRET', algorithm: sha256 }
    retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
    payload: { excludeFields: [internal_notes], includePreviousValues: true }
```

:::callout
**Validation.** Les `name` de webhooks doivent être uniques au sein d'une table, et tout champ référencé par `payload.includeFields` / `excludeFields` doit nommer un véritable champ (ou l'`id` implicite). Les URL invalides et les schémas non-`http(s)` sont rejetés au moment du décodage de la configuration.
:::