Bonnes pratiques emailing

Qu’est-ce qu’un webhook ? Suivi des événements d’email en temps réel avec Mailjet

Découvrez ce qu'il en est exactement et pourquoi vous en avez besoin. Le suivi des événements est facile avec les webhooks, c'est pourquoi Mailjet vous offre la possibilité de les utiliser avec nous.
Image pourQu’est-ce qu’un webhook ? Suivi des événements d’email en temps réel avec Mailjet
décembre 20, 2022

Les webhooks sont un moyen puissant de recevoir des notifications en temps réel lorsque des événements se produisent dans vos campagnes d’emailing. Ce guide complet vous apprendra ce que sont les webhooks, comment ils fonctionnent avec les systèmes de messagerie, et comment mettre en œuvre la fonctionnalité webhook de Mailjet pour suivre en temps réel les événements de messagerie tels que les ouvertures, les clics, les rebonds et plus encore.

À la fin de ce guide, vous saurez comment configurer et optimiser les points de terminaison des webhooks, gérer les différents types d’événements et mettre en œuvre les bonnes pratiques pour un traitement fiable et évolutif des événements de messagerie.

Qu’est-ce qu’un webhook ?

Un webhook est un moyen simple pour un système de notifier à un autre que « quelque chose vient de se produire ». Il s’agit d’une requête HTTP POST envoyée à une URL que vous fournissez (votre point de terminaison « webhook ») et qui contient une charge utile JSON décrivant l’événement. Contrairement aux API que vous interrogez selon un calendrier, les webhooks sont pilotés par des événements et ne transmettent des données que lorsqu’il y a quelque chose de nouveau à signaler.

Les webhooks sont la version Internet d’un appel téléphonique : au lieu de vérifier à plusieurs reprises si quelque chose s’est produit, le système vous appelle immédiatement lorsque c’est le cas.

Pourquoi les équipes utilisent-elles les webhooks ?

Les webhooks offrent plusieurs avantages pour l’email marketing et les flux de travail des emails transactionnels :

  • Notifications en temps réel : mettez votre application à jour dès qu’un email est ouvert ou qu’un lien est cliqué
  • Une assistance et des opérations plus rapides : déclenchez des alertes en cas d’augmentation des taux de rebond ou de blocage
  • Une gestion des données plus propre : synchronisez automatiquement les désabonnements et les rebonds avec votre CRM
  • Personnalisation accrue : envoyez des messages de suivi lorsque les clients s’engagent (ou non)
  • De meilleures statistiques : diffusez des événements en direct dans vos tableaux de bord ou votre entrepôt de données

Interrogation d’API ou webhook

Comprendre la différence entre les webhooks et l’interrogation traditionnelle de l’API de messagerie permet d’illustrer pourquoi les webhooks sont souvent le meilleur choix :

Interrogation d’APIWebhooks
Extrayez des données avec un minuteur, même si rien n’a changéNotifications push basées sur des événements
Plus de demandes et d’utilisation de la bande passanteMoins de demandes, plus d’efficacité
Informations stratégiques retardées en raison des intervalles d’interrogationMises à jour instantanées en cas d’événements
Programmation complexe et gestion des étatsDes flux d’automatisation plus simples

Fonctionnement des webhooks d’email Mailjet

Mailjet peut envoyer des notifications webhook pour les événements de messagerie suivants :

  • sent : l’email a été envoyé
  • open : le destinataire a ouvert le email
  • click : le destinataire a cliqué sur un lien dans le email
  • bounce : l’email a rebondi (de façon temporaire ou permanente)
  • blocked : l’email a été bloqué par le serveur du destinataire
  • spam : l’email a été marqué comme spam
  • unsub : le destinataire s’est désabonné

Comprendre les charges utiles des webhooks

Chaque webhook contient une charge utile JSON avec des informations spécifiques à l’événement. Voici des exemples de types d’événements courants :

Charge utile d’un événement d’ouverture

                            

                                {
  "event": "open",
  "time": 1433103519,
  "MessageID": 19421777396190490,
  "email": "api@mailjet.com",
  "mj_campaign_id": 7173,
  "mj_contact_id": 320,
  "customcampaign": "",
  "CustomID": "helloworld",
  "Payload": "",
  "ip": "127.0.0.1",
  "geo": "US",
  "agent": "Mozilla/5.0 ..."
}
                            
                        

Charge utile d’un événement de rebond

                            

                                {
  "event": "bounce",
  "time": 1430812195,
  "MessageID": 13792286917004336,
  "email": "bounce@mailjet.com",
  "blocked": true,
  "hard_bounce": true,
  "error_related_to": "recipient",
  "error": "user unknown"
}

                            
                        

Traitement des différents types d’événements

Chaque type d’événement nécessite des stratégies de gestion différentes :

  • Désabonné/spam : supprimer immédiatement le contact dans tous les systèmes
  • Rebond permanent : supprimer de la liste de diffusion et arrêter les envois futurs
  • Bloqué : inspecter les détails de l’erreur et les informations sur le fournisseur pour diagnostiquer les problèmes de délivrabilité
  • Clic/ouverture : déclencher des campagnes de suivi, évaluer l’engagement et personnaliser les parcours client

Bonnes pratiques pour les webhooks Mailjet

Le respect de ces bonnes pratiques garantit un traitement fiable des webhooks et des performances optimales :

Traitement des réponses

  • Renvoyez HTTP 200 OK immédiatement : accusez réception le plus rapidement possible
  • Traitez de manière asynchrone : faites persister la charge utile dans une file d’attente ou une base de données, puis la traiter séparément

Fiabilité et sécurité

  • Utilisez HTTPS : hébergez votre point de terminaison sur une connexion sécurisée
  • Mettez en œuvre l’authentification : protégez votre point de terminaison avec une authentification de base ou des clés API
  • Surveillez les échecs : suivez les réponses non-200 pour éviter la suspension de l’URL

Optimisation des performances

  • Minimisez le temps de traitement : effectuez un travail minimal dans le gestionnaire de la demande afin d’éviter les dépassements de délai
  • Utilisez le regroupement d’événements : configurez Version=2 pour regrouper plusieurs événements en une seule demande
  • Mettez en place des URL de secours : configurez des points de terminaison de basculement pour maintenir le flux d’événements pendant les pannes

Comportement de réessai

Mailjet relance automatiquement les livraisons de webhook qui ont échoué pendant une durée maximale de 24 heures si votre point de terminaison ne renvoie pas une réponse 200 OK. Si des erreurs répétées persistent, l’URL du webhook peut être suspendue. Vous pouvez configurer une URL de sauvegarde pour assurer la livraison continue des événements.

Configuration des webhooks Mailjet

Vous pouvez configurer les webhooks Mailjet à l’aide de l’API ou de l’interface web. Voici les deux approches :

Option A : Configuration de l’API (recommandée pour les développeurs)

Cette méthode offre plus de contrôle et est idéale pour les déploiements automatisés.

Étape 1 : Choisissez vos types d’événements

Déterminez les événements que vous souhaitez suivre : envoi, ouverture, clic, rebond, blocage, spam ou désabonnement.

Étape 2 : Créez le webhook via l’API

Utilisez la ressource eventcallbackurl pour configurer votre webhook :

                            

                                curl -X POST \
  https://api.mailjet.com/v3/REST/eventcallbackurl \
  -H 'Authorization: Basic <base64_encoded_api_key:secret>' \
  -H 'Content-Type: application/json' \
  -d '{
  "EventType": "open",
  "Url": "https://example.com/webhooks/mailjet/open",
  "Version": 2
  }'

                            
                        

Notes de configuration :

  • Version=2 permet de regrouper des événements en une seule requête POST
  • Définissez « isBackup »: true sur une URL secondaire pour créer un point de terminaison de basculement

Étape 3 : Testez votre intégration

Envoyez un email de test et effectuez l’action suivie (ouverture, clic, etc.) pour vérifier que vous recevez des événements webhook.

Option B : Configuration de l’interface web (option sans code)

Pour les équipes qui préfèrent une interface visuelle :

  1. Connectez-vous à app.mailjet.com et accédez aux Paramètres du compte
  2. Sous REST API, sélectionnez « Notifications d’événements (webhooks) »
  3. Ajoutez une URL pour tous les événements ou définissez des URL dédiées par type d’événement
  4. Testez avec des événements réels plutôt qu’avec la fonction Tester, qui envoie des charges utiles vides

Exemples de mise en œuvre des webhooks

Voici des implémentations minimales de récepteurs webhook dans les langages de programmation les plus courants :

Node.js avec express

                            

                                const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/mailjet/open', (req, res) => {
 // 1. Faites persister rapidement les données de l'événement
  console.log('Webhook reçu :', req.body);
  // À faire : Sauvegarder dans la file d'attente ou la base de données
  // await saveToQueue(req.body);

 // 2. Accuser réception immédiatement
  res.status(200).send('ok');
});

app.listen(3000, () => {
  console.log('Serveur de webhook exécuté sur le port 3000');
});

                            
                        

Python avec flask

                            

                                from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/mailjet/open', methods=['POST'])
def handle_open_event():
  data = request.get_json()

  # Traiter les données du webhook
  print(f&quot;Webhook reçu : {data}&quot;)
  # À faire : Sauvegarder dans la file d'attente ou la base de données
  # save_to_queue(data)

  return jsonify({"status": "ok"}), 200

if __name__ == '__main__':
  app.run(port=3000)
                            
                        

Conseils de configuration avancée

Voici quelques conseils pour vous aider à tirer le meilleur parti des webhooks.

Traitement par lots à l’échelle

Utilisez Version=2 dans votre configuration de webhook pour réduire la surcharge HTTP en recevant plusieurs événements dans des requêtes groupées :

                            

                                {
  "EventType": "open",
  "Url": "https://example.com/webhooks/mailjet/batch",
  "Version": 2
}
                            
                        

Corrélation et suivi des événements

Utilisez les paramètres CustomID et EventPayload dans vos appels Send API pour faciliter la corrélation des événements webhook avec vos systèmes internes :

                            

                                {
  "Messages": [{
    "To": [{"Email": "user@example.com"}],
    "Subject": "Welcome!",
    "TextPart": "Welcome to our service!",
    "CustomID": "user-123-welcome",
    "EventPayload": "campaign=onboarding&segment=new_users"
  }]
}

                            
                        

Diffusion en continu d’événements à l’échelle de l’entreprise

Pour les applications à fort volume, envisagez de diffuser les événements en continu vers des services de file d’attente tiers :

  • Azure Service Bus
  • Amazon SQS
  • Google Cloud Pub/Sub

Foire aux questions

Quels événements Mailjet envoie-t-il aux webhooks ?

Mailjet envoie les événements d’envoi, d’ouverture, de clic, de rebond, de blocage, de spam et de désabonnement. Chacun contient le MessageID, les identifiants du contact et de la campagne, ainsi que des détails spécifiques à l’événement (tels que l’url pour les événements de clic).

Quelle est la rapidité de livraison des événements ?

Les événements sont transmis peu de temps après leur survenance, généralement en quelques secondes. Si votre point de terminaison ne répond pas par HTTP 200 OK, Mailjet retente la livraison pendant une période pouvant aller jusqu’à 24 heures.

Puis-je réduire le nombre d’appels de webhook ?

Oui. Configurez la livraison groupée en définissant Version=2 sur votre eventcallbackurl afin que Mailjet regroupe plusieurs événements en une seule requête POST.

Comment sécuriser le point de terminaison de mon webhook ?

Utilisez HTTPS, protégez le point de terminaison avec une authentification de base et limitez l’accès au moyen d’un filtrage IP ou de passerelles API. Traitez toujours les données utiles côté serveur et n’exposez jamais les points de terminaison des webhooks aux applications clientes.

Liste de contrôle pour la configuration rapide

Suivez cette liste de contrôle pour mettre en œuvre les webhooks de Mailjet avec succès :

  • [ ] Créer et sécuriser un point de terminaison HTTPS public
  • [ ] Configurer eventcallbackurl via l’API ou l’interface web
  • [ ] Mettre en œuvre des réponses HTTP 200 OK rapides avec un traitement asynchrone
  • [ ] Ajouter CustomID et EventPayload à vos envois d’emails pour faciliter la corrélation
  • [ ] Surveiller les échecs des webhooks et configurer des URL de secours
  • [ ] Configurer la diffusion d’événements en continu vers vos systèmes de statistiques ou d’alerte

Prochaines étapes et ressources supplémentaires

Maintenant que vous comprenez les principes fondamentaux et la mise en œuvre des webhooks, envisagez d’explorer ces fonctionnalités Mailjet connexes :

Résumé

Les webhooks constituent un moyen puissant et efficace de recevoir des notifications en temps réel sur les événements liés aux emails. En mettant en œuvre les webhooks Mailjet avec une gestion appropriée des erreurs, des mesures de sécurité et un traitement asynchrone, vous pouvez créer des flux d’emails réactifs et pilotés par les données qui améliorent l’expérience client et l’efficacité opérationnelle.

N’oubliez pas de commencer simplement, de suivre de près votre mise en œuvre et d’adapter le traitement des webhooks à l’augmentation du volume de vos emails. Avec les bases fournies dans ce guide, vous êtes prêt à exploiter toute la puissance du suivi des événements de messagerie en temps réel.