# Configurer un webhook

> Créez un endpoint de webhook, choisissez ses événements, ajoutez des filtres de contenu, envoyez un événement de test, activez ou désactivez le webhook, ou effectuez une rotation du secret.

Dans ce guide, vous créez un webhook, le limitez aux événements dont vous avez besoin et vérifiez que votre endpoint reçoit des requêtes signées. Vous pouvez tout faire dans le tableau de bord ou avec l’[API des webhooks](/fr/docs/api-reference/webhooks/).

## Avant de commencer

- Une URL publique qui accepte les requêtes `POST`. HTTPS est vivement recommandé. Les URL sur `localhost` ou sur des plages d’IP privées sont refusées ; pour le développement local, utilisez un tunnel comme ngrok ou Cloudflare Tunnel.
- Un endpoint qui conserve le corps brut de la requête pour pouvoir [vérifier la signature](/fr/docs/webhooks/request-signature/).
- Pour l’API, une clé **Full Access**.
- Un emplacement de webhook libre. Pay as you go inclut 3 endpoints, Pro 10, Business et Custom 100.

## Créer le webhook

**Tableau de bord**

  1. **Ouvrez la page Webhooks.** Accédez à **Email API → Webhooks** et sélectionnez **Add webhook**.

  2. **Saisissez un nom et une URL.** Le nom doit être unique dans l’espace de travail, par exemple `Production events`. L’URL est celle de votre endpoint, par exemple `https://acme.com/webhooks/emailit`. Sélectionnez **Create**.

  3. **Copiez le secret.** La boîte de dialogue affiche le secret du webhook, qui commence par `whsec_`, avec l’avertissement « You can see the webhook secret only once. Store it safely. » Copiez-le dans l’environnement de votre application, par exemple sous le nom `EMAILIT_WEBHOOK_SECRET`, puis sélectionnez **Done**.

  Un webhook créé dans le tableau de bord est abonné à tous les types d’événements. L’onglet **Settings** du webhook s’ouvre pour que vous puissiez le restreindre.

**API**

  Appelez [Créer un webhook](/fr/docs/api-reference/webhooks/create/). Listez les types d’événements dans `events`, ou définissez `all_events` sur `true`. La réponse `201` contient le `secret`.

```bash
curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'
```

  Contrairement au tableau de bord, l’API utilise par défaut `all_events: false` et une liste `events` vide : un webhook créé sans l’un ni l’autre ne reçoit rien. Un nom en double renvoie `409` ; atteindre la limite d’endpoints de votre forfait renvoie `422` avec `usage.used` et `usage.limit`.

## Choisir les événements

Un webhook reçoit soit tous les types d’événements, soit uniquement ceux que vous sélectionnez.

**Tableau de bord**

  Dans l’onglet **Settings** du webhook, désactivez **All events**, puis sélectionnez les types dans la carte **Events**. Les événements sont regroupés par ressource (**Emails**, **Domains**, **Audiences**, **Subscribers**, **Contacts**, **Templates**, **Suppressions**, **Email Verifications**, **Email Verification Lists**), et chaque groupe a une case **Select all**. Sélectionnez **Save**.

  Le sélecteur ne liste pas tous les types qu’Emailit envoie. `email.canceled`, `email.held`, `email.unsubscribed`, `email.resubscribed`, `subscriber.resubscribed` et les événements `campaign.*` parviennent aux webhooks dont l’option **All events** est activée, ou vous pouvez les ajouter à la liste via l’API. Le groupe **Deprecated** contient d’anciens noms d’événements qui ne sont plus envoyés. Consultez [Types d’événements](/fr/docs/webhooks/event-types/).

**API**

  Appelez [Mettre à jour un webhook](/fr/docs/api-reference/webhooks/update/). `events` remplace toute la liste. Définir `all_events` sur `true` vide la liste.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'
```

## Filtrer les événements par contenu

Pro, Business, Custom

Un filtre de contenu ne livre un événement que si ses données correspondent à vos règles. Les filtres s’appliquent en plus de la sélection d’événements : un événement doit être sélectionné *et* correspondre au filtre.

Utilisez-le pour répartir le trafic entre plusieurs endpoints, par exemple un webhook par gamme de produits, ou pour écarter des événements que vous ignoreriez de toute façon dans votre code.

- **Mode de correspondance :** **All rules match** (`all`) ou **Any rule matches** (`any`).
- **Règles :** 25 au maximum. Chaque règle comporte un champ, un opérateur et une valeur.
- **Champ :** un chemin à points dans le `data.object` de l’événement, par exemple `to`, `status`, `meta.plan` ou, pour les événements de clic, `link.url`. Le préfixe `payload.` est facultatif : `payload.from` et `from` sont équivalents.
- **Les comparaisons sont sensibles à la casse** et comparent les valeurs sous forme de texte, sauf `greater_than` et `less_than`, qui comparent des nombres.

| Opérateur | Correspond lorsque le champ |
| --- | --- |
| `equals` / `not_equals` | Est / n’est pas exactement égal à la valeur. |
| `contains` / `not_contains` | Contient / ne contient pas la valeur. |
| `starts_with` / `ends_with` | Commence / se termine par la valeur. |
| `greater_than` / `less_than` | Est un nombre supérieur / inférieur à la valeur. |
| `is_set` / `is_not_set` | A une valeur non vide / est absent ou vide. Aucune valeur nécessaire. |
| `in` / `not_in` | Est égal / n’est égal à aucune des valeurs d’un tableau. Envoyez le tableau via l’API, comme dans l’exemple ci-dessous. |

**Tableau de bord**

  Dans l’onglet **Settings** du webhook, repérez la carte **Filter**. Choisissez le mode de correspondance, ajoutez des règles avec un champ, un opérateur et une valeur, puis sélectionnez **Save**. Laissez les règles vides pour livrer tous les événements sélectionnés. Sur Pay as you go, la carte est verrouillée et affiche **Upgrade**.

**API**

  Envoyez `filter` avec [Créer un webhook](/fr/docs/api-reference/webhooks/create/) ou [Mettre à jour un webhook](/fr/docs/api-reference/webhooks/update/). Définissez-le sur `null` pour le supprimer. Sur Pay as you go, un filtre renvoie `403` avec `"error": "plan_required"`.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'
```

Autres exemples :

| Objectif | Règle |
| --- | --- |
| Uniquement les e-mails reçus sur une adresse précise | `to` `equals` `support@inbound.acme.com` |
| Un seul domaine d’expéditeur | `from` `ends_with` `@billing.acme.com` |
| Uniquement les e-mails que vous avez étiquetés avec des métadonnées | `meta.source` `equals` `checkout` |
| Uniquement les clics sur votre page de tarifs | `link.url` `starts_with` `https://acme.com/pricing` |
| Uniquement les e-mails qui contiennent un ID client | `meta.customer_id` `is_set` |

> **Les champs varient selon le type d’événement:** Une règle portant sur un champ absent de l’événement ne correspond jamais. Les événements de statut d’e-mail ont `to` et `from` au premier niveau, mais les événements de clic et de chargement les imbriquent sous `email.rcpt_to` et `email.mail_from`, et les événements de contact ont `email`. Avec **All rules match**, un webhook filtré sur `to` écarte silencieusement tous les clics. Utilisez des webhooks distincts par catégorie d’événement, ou **Any rule matches** avec une règle par structure. Vérifiez les noms de champs dans la [référence des événements](/fr/docs/webhooks/event-types/).

Si un espace de travail passe à Pay as you go, les filtres existants restent enregistrés mais sont ignorés, et tous les événements sélectionnés sont livrés.

## Envoyer un événement de test

Un test envoie immédiatement un exemple d’événement à votre URL, signé avec le secret actuel du webhook. Les événements sélectionnés et les filtres sont ignorés, la requête ne fait l’objet d’aucune nouvelle tentative et elle n’apparaît pas dans l’onglet **Requests**. Chaque webhook autorise 5 tests par minute.

**Tableau de bord**

  Sur la page du webhook, ouvrez le menu d’actions (**…**) et sélectionnez **Send test**. Choisissez un type d’événement et sélectionnez **Send test**. La boîte de dialogue affiche « Your endpoint returned 200 » (ou le statut renvoyé par votre endpoint) et le corps de la réponse. « Could not reach the endpoint » signifie que la requête n’a pas obtenu de réponse HTTP, par exemple à cause d’une erreur DNS, d’un timeout ou d’une redirection.

**API**

  Appelez [Envoyer un événement de test](/fr/docs/api-reference/webhooks/test/) avec n’importe quel type d’événement.

```bash
curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'
```

  La réponse contient `ok`, `status_code`, `body` (la réponse de votre endpoint, 2 000 caractères au maximum), `type` et le `payload` envoyé.

Les événements de test utilisent des données d’exemple, avec un `event_id` qui commence par `evt_test_`, et leur structure peut légèrement différer de celle des événements réels. Construisez votre gestionnaire à partir de la [référence des événements](/fr/docs/webhooks/event-types/) et confirmez avec un envoi réel.

## Activer ou désactiver un webhook

Désactivez un webhook pour arrêter les livraisons sans perdre ses paramètres, par exemple pendant une maintenance.

- **Tableau de bord :** ouvrez le menu d’actions et sélectionnez **Disable webhook** ou **Enable webhook**. La page du webhook affiche le statut **Enabled** ou **Disabled**.
- **API :** appelez [Mettre à jour un webhook](/fr/docs/api-reference/webhooks/update/) avec `{"enabled": false}` ou `{"enabled": true}`.

Tant qu’un webhook est désactivé, les nouveaux événements ne sont pas mis en file d’attente pour lui, et les requêtes qui attendent déjà une nouvelle tentative sont suspendues. Les événements survenus pendant la désactivation ne sont pas livrés plus tard ; si vous en avez besoin, lisez-les avec l’[API des événements](/fr/docs/logs/events/#reconcile-missed-webhook-events). Emailit désactive aussi automatiquement les webhooks après 3 jours d’échecs ; consultez [Nouvelles tentatives et échecs](/fr/docs/webhooks/retries-and-failures/).

La suppression d’un webhook entraîne la perte de tous ses événements en attente.

## Effectuer une rotation du secret

Effectuez une rotation du secret s’il a pu fuiter, ou régulièrement, par précaution.

- **Tableau de bord :** ouvrez le menu d’actions, sélectionnez **Webhook secret**, puis **Reset**. Le nouveau secret n’est affiché qu’une seule fois.
- **API :** appelez [Effectuer une rotation du secret de signature](/fr/docs/api-reference/webhooks/reset-secret/). La réponse contient le nouveau `secret`. [Récupérer un webhook](/fr/docs/api-reference/webhooks/get/) renvoie aussi le secret actuel.

L’ancien secret cesse immédiatement de fonctionner, et toutes les requêtes suivantes, y compris les nouvelles tentatives d’événements plus anciens, sont signées avec le nouveau. Pour effectuer la rotation sans rejeter de requêtes, faites accepter les deux secrets à votre endpoint pendant quelques minutes, réinitialisez le secret, déployez la nouvelle valeur, puis retirez l’ancienne.

## Vérifier le résultat

1. Envoyez un événement de test et vérifiez que votre endpoint renvoie `2xx`.
2. Envoyez un vrai e-mail, ou déclenchez l’événement auquel vous êtes abonné.
3. Dans l’onglet **Requests** du webhook, la requête affiche **Delivered**. L’heure **Last used** du webhook est mise à jour.

## Voir aussi

  - [Vérifier les signatures](/fr/docs/webhooks/request-signature/)
  - [Requêtes de webhook](/fr/docs/webhooks/webhook-requests/)
  - [Types d’événements](/fr/docs/webhooks/event-types/)
  - [Nouvelles tentatives et échecs](/fr/docs/webhooks/retries-and-failures/)

---
Source: https://emailit.com/fr/docs/webhooks/set-up/