Configurer un webhook

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.

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

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"]
  }'

Choisir les événements

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

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

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.

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 :

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.

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"}'

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 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 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. Emailit désactive aussi automatiquement les webhooks après 3 jours d’échecs ; consultez Nouvelles tentatives et échecs.

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. La réponse contient le nouveau secret. Récupérer un webhook 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