Configurer un webhook

Un webhook est une adresse sur votre propre serveur à laquelle 2Mail envoie un message dès qu'il se passe quelque chose avec un e-mail : remis, en bounce, ouvert. Votre boutique ou votre CRM sait ainsi en quelques secondes ce qu'il est advenu d'un message, sans que vous ayez à consulter le tableau de bord.

Ce qu'il vous faut

• une adresse sur votre serveur accessible en https et capable de recevoir des requêtes ; un webhook sans chiffrement n'est pas accepté
• un bout de code derrière cette adresse qui traite les données
• des droits d'administrateur dans votre compte 2mail

Étape 1 : créer le webhook

1. Ouvrez dans le tableau de bord la section des webhooks et créez-en un nouveau.
2. Saisissez l'adresse de votre point de terminaison.
3. Choisissez les événements que vous voulez recevoir : remise, bounce, ouverture, ou une combinaison. Commencez par les bounces — c'est l'événement sur lequel vous devez agir le plus vite.
4. Enregistrez. Le tableau de bord affiche une clé secrète avec laquelle chaque appel est signé. Conservez-la dans la configuration de votre application.

Étape 2 : vérifier la signature

N'importe qui peut envoyer une requête à votre adresse. Chaque appel de 2Mail porte donc une signature dans l'en-tête, calculée avec la clé secrète sur le contenu. Recalculez cette signature de votre côté et rejetez les requêtes dont elle ne correspond pas. Ne sautez pas cette étape : sans contrôle, un tiers peut faire croire à votre système qu'un message est en bounce.

Étape 3 : répondre vite

Répondez immédiatement avec un code de statut de la série 200 et traitez les données ensuite, par exemple via une file d'attente. Si votre traitement dure trop longtemps ou si vous répondez par une erreur, 2Mail considère l'appel comme échoué et réessaie plus tard. Veillez à ce que votre code puisse recevoir deux fois le même message sans actions en double : utilisez l'identifiant du message pour reconnaître les répétitions.

Étape 4 : tester

Envoyez un message de test à une adresse que vous gérez et vérifiez que la remise arrive sur votre point de terminaison. Pour un bounce, testez avec une adresse qui n'existe certainement pas sur un domaine qui existe. Le tableau de bord affiche par webhook les derniers appels, avec la réponse de votre serveur — vous y voyez tout de suite si votre point de terminaison a renvoyé autre chose qu'un 200.

Ce que vous en faites

• Lors d'un hard bounce, marquer l'adresse dans votre CRM pour qu'un commercial ne continue pas à l'utiliser.
• Lors d'une remise, afficher dans l'historique de commande que la confirmation est arrivée — cela évite des appels.
• Lors d'une ouverture, planifier une tâche de suivi, par exemple après un devis.

Là où ça coince

• Aucun appel — l'adresse n'est accessible qu'en interne, ou un pare-feu bloque les requêtes venant de l'extérieur.
• La signature ne correspond jamais — vous la calculez sur un contenu modifié ; utilisez le contenu brut de la requête.
• Actions en double — votre point de terminaison répond trop lentement et reçoit donc des répétitions.

Les webhooks font partie de l'API e-mail ; créer une clé API est la première étape si votre application veut aussi envoyer.

Ça ne marche pas ?

Communiquez-nous via contact l'adresse de votre point de terminaison et l'heure du test. Nous vous montrons ce que votre serveur nous a répondu.