Votre guide d’utilisation des webhooks

Vous savez déjà qu’un email ne s’envoie pas pour être oublié aussitôt. Lorsque vous envoyez un message, vous souhaitez savoir comment le suivre et réagir en cas de problème, n’est-ce pas ? Après tout, savoir si vos emails sont performants vous aide à maintenir votre réputation d’expéditeur et vos taux de délivrabilité. En reliant un webhook à votre CRM préféré, votre équipe peut consulter facilement et rapidement les statistiques d’engagement pertinentes et prendre des décisions basées sur des informations actualisées à la minute près. Avant de nous plonger dans les cas d’utilisation, nous devrions aborder les bases des webhooks.

Pour faire simple, les webhooks sont des notifications qui envoient des données d’événement à une autre application après qu’un événement s’est produit. Ils fonctionnent comme une API inversée : au lieu d’interroger un point de terminaison d’API à plusieurs reprises pour obtenir des mises à jour, le webhook vous envoie la mise à jour via une requête HTTP. Webhooks sont un moyen pour les applications de communiquer des informations grâce à l’automatisation et à des rappels HTTP personnalisés (similaires aux SMS), généralement déclenchés par un événement tel qu’une livraison d’email réussie ou une notification de rebond.

Dans une architecture orientée événements, cela devient particulièrement puissant. Par exemple, lorsque vous fournissez à votre application bancaire vos informations de dépôt direct et votre numéro de téléphone, et qu’elle vous envoie un SMS pour vous informer que vous venez de recevoir un dépôt, c’est un webhook qui permet à votre banque d’envoyer ce SMS avec les mises à jour pertinentes.

Les webhooks sont utilisés pour créer des notifications concernant des événements spécifiques. Étant donné que les webhooks sont basés sur HTTP POST, ils sont faciles à utiliser. De plus, les scripts de webhook peuvent être écrits dans presque n’importe quel langage de script de votre choix, notamment curl, Ruby, Python, PHP, Java, C# et Go. Une fois que les données du webhook ont été capturées, elles peuvent être stockées dans une base de données et utilisées pour évaluer l’efficacité des campagnes d’emailing ou enrichir les profils des destinataires. Utilisez-les dans divers flux de travail, de l’enregistrement des confirmations de commande e-commerce à l’intégration des événements de paiement Stripe en temps réel dans votre backend.

Vous pouvez également obtenir des données plus détaillées que celles fournies par un tableau de bord standard en personnalisant les statistiques renvoyées par le webhook.

Alors, comment fonctionne un webhook ?

Lorsque l’événement se produit, le site source envoie une requête HTTP POST à une URL que l’équipe de développement a configurée pour recevoir le webhook. L’équipe de développement peut les configurer de manière à ce que les événements sur un site déclenchent un comportement sur un autre. Ensuite, les données de ce webhook peuvent être envoyées à l’URL configurée sous forme de charge utile de webhook au format JSON ou XML. Voici les quatre étapes à suivre :

La première décision que l’équipe de développement prend lorsqu’elle planifie le suivi de ses emails et sa réponse est de savoir exactement quelles données elle souhaite récupérer. Si l’objectif est de savoir quand les emails envoyés génèrent des rebonds, l’URL de l’utilisateur peut exécuter un script sur les requêtes POST entrantes pour capturer et enregistrer l’adresse email ayant généré un rebond dans une base de données locale. Le même script pourrait être enrichi pour capturer le nom du destinataire, l’objet ou tout autre paramètre fourni par le webhook.

Commençons par explorer la requête POST du webhook, qui peut être encodée de la manière suivante : application/x-www-form-urlencoded pour la plupart des messages, et multipart/form-data s’il y a une pièce jointe incluse avec le message. La méthode de requête POST est conçue pour demander à un serveur web d’accepter les données incluses dans le corps du message de la requête pour les stocker.

Voici un exemple de requête HTTP POST effectuée par Mailgun vers une URI chez Runescope. Notez que l’en-tête Content Type est défini sur application/x-www-form-urlencoded :

                                

                                    ACCEPT: */* 
ACCEPT-ENCODING: GZIP 
CONNECTION: CLOSE 
CONTENT-LENGTH: 1325 
CONTENT-TYPE: APPLICATION/X-WWW-FORM-URLENCODED 
HOST: 
USER-AGENT: MAILGUN/TREQ-0.2.
                                
                            

Le corps du message contient des paramètres stockés sous forme de paires clé-valeur. (Nous reviendrons plus en détail sur les données publiées dans la section ci-dessous.) Comme les données sont encodées, elles ressembleront simplement à du charabia. Voici à quoi pourrait ressembler le corps décodé typique :

                                

                                    DOMAIN: BEATNIKZ.NET
EVENT: DELIVERED
MESSAGE-HEADERS: [["RECEIVED", "BY LUNA.MAILGUN.NET WITH HTTP; WED, 07 JAN 2015 00:44:03 +0000"], ["MIME-VERSION", "1.0"], ["CONTENT-TYPE", ["TEXT/PLAIN", {"CHARSET": "ASCII"}]], ["SUBJECT", "HELLO"], ["FROM", "TAG TEST "], ["TO", "MGBOX01@GMAIL.COM"], ["X-MAILGUN-TAG", "WEB APP SEPTEMBER NEWSLETTER"], ["X-MAILGUN-TAG", "NEWSLETTERS"], ["MESSAGE-ID", ""], ["X-MAILGUN-SID", "WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0="], ["DATE", "WED, 07 JAN 2015 00:44:11 +0000"], ["SENDER", "NOLAN=YBEATNIKZ.NET@BEATNIKZ.NET"], ["CONTENT-TRANSFER-ENCODING", ["7BIT", {}]]]
MESSAGE-ID: 
RECIPIENT: MGBOX01@GMAIL.COM
SIGNATURE: EB9FE5C673522299A2259052E56487E54F4D2486A0F1582E91D2C17114A6398
TIMESTAMP: 1420591452
TOKEN: E40542A95B5A6989B5E226CC0E9BB2F120478AF8EE594F884C
X-MAILGUN-SID: WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0=
X-MAILGUN-TAG: WEB APP SEPTEMBER NEWSLETTER
X-MAILGUN-TAG: NEWSLETTERS
                                
                            

Lors de l’envoi d’un email, certains services d’emailing permettent aux utilisateurs de joindre des données à leurs messages en transmettant des données personnalisées à l’API ou aux points de terminaison SMTP. Les données seront représentées sous la forme d’un en-tête dans l’email et sont généralement formatées en JSON. Ces données personnalisées seraient ensuite incluses dans tous les événements de webhook liés à l’email qui les contient. Plusieurs en-têtes peuvent être inclus et leurs valeurs seront combinées.

Exemple :

                                

                                    X-MAILGUN-VARIABLES: {"FIRST_NAME": "JOHN", "LAST_NAME": "SMITH"}
X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}
                                
                            

Pour ajouter cet en-tête à un message :

                                

                                    USING API: PASS THE FOLLOWING PARAMETER, "V:MY-CUSTOM-DATA" => "{"MY_MESSAGE_ID": 123}".
USING SMTP: ADD THE FOLLOWING HEADER TO THE EMAIL, "X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}".
                                
                            

Alternativement, vous pouvez facilement supprimer un webhook existant :

Il est parfois utile de classer le trafic d’emails sortants en fonction de certains critères, par exemple en séparant les emails d’inscription des emails de récupération de mot de passe ou des commentaires des utilisateurs. Le service d’emailing peut permettre de baliser chaque message sortant avec une valeur personnalisée. Ces valeurs deviennent des balises qui peuvent rappeler ou agréger les statistiques de délivrabilité. Pour joindre une balise à un message de webhook, fournissez-lui une ou plusieurs balises O:TAG.

Exemple de code de balisage :

                                

                                    CURL -S --USER 'API:YOUR_API_KEY' \

HTTPS://API.MAILGUN.NET/V3/YOUR_DOMAIN_NAME/MESSAGES \
-F FROM='SENDER BOB ' \
-F TO='ALICE@EXAMPLE.COM' \
-F SUBJECT='HELLO' \
-F TEXT='TESTING SOME MAILGUN AWESOMNESS!' \
-F O:TAG='SEPTEMBER NEWSLETTER' \
-F O:TAG='NEWSLETTERS'
                                
                            

Afin de recevoir les données d’un webhook, les utilisateurs doivent fournir à leur service d’emailing une URL vers laquelle livrer les requêtes. Cela signifie qu’ils doivent également configurer l’URL dans leur application, afin qu’elle soit accessible depuis le web public et depuis différentes adresses IP (d’où le besoin de sécurité). Les webhooks du service d’emailing enverront ensuite les données POST à l’URL au format application/x-www-form-urlencoded ou multipart/form-data.

La dernière étape consiste à ajouter des scripts à l’URL qui capturent les données fournies par les webhooks et à les traiter de la manière que l’équipe de développement jugera appropriée. C’est ici que vous pouvez faire preuve de créativité mais aussi de précision quant aux attributs que vous souhaitez collecter. La meilleure façon de voir cela est de prendre un exemple.

Un cas d’utilisation pour un webhook pourrait être de suivre les rebonds d’emails. Pour cela, vous devrez capturer une pièce jointe et stocker le fichier localement. Par exemple, le code suivant utilise une combinaison du micro-framework Flask pour Python, et de la bibliothèque HTTP Requests. Voici une application Flask rapide pour capturer un fichier à partir d’un webhook de rebond, conserver le nom de fichier natif et le stocker localement sur votre serveur web.

                                

                                    FROM FLASK IMPORT FLASK
FROM FLASK IMPORT REQUEST
FROM WERKZEUG IMPORT SECURE_FILENAME
APP = FLASK(__NAME__)

@APP.ROUTE('/WEBHOOK', METHODS=['GET', 'POST'])
DEF TRACKING():
#CHECKS IF THE REQUEST IS A POST
IF REQUEST.METHOD == 'POST':
F = REQUEST.FILES['ATTACHMENT-1']
# OBTAINS THE FILESTORAGE INSTANCE FROM REQUEST
FILENAME = SECURE_FILENAME(F.FILENAME)
F.SAVE('/HOME/DIRECTORY/WEBHOOK/'+ FILENAME)
PRINT FILENAME
RETURN "OK"
IF __NAME__ == '__MAIN__':
APP.RUN(HOST='0.0.0.0', PORT=100, DEBUG=TRUE)
                                
                            

Pour le voir en action, exécutez votre application et collez l’URL (par exemple : http://yourdomainhere.com:100/webhook) dans le webhook de rebond et cliquez sur « Tester le webhook ». Vous obtiendrez un fichier nommé « message.mime » avec :

                                

                                    RECEIVED: BY LUNA.MAILGUN.NET WITH SMTP MGRT 8734663311733; FRI, 03 MAY 2013 18:26:27 +0000
CONTENT-TYPE: MULTIPART/ALTERNATIVE; BOUNDARY="EB663D73AE0A4D6C9153CC0AEC8B7520"
MIME-VERSION: 1.0
SUBJECT: TEST BOUNCES WEBHOOK
FROM: BOB 
TO: ALICE 
MESSAGE-ID: 
LIST-UNSUBSCRIBE: 
X-MAILGUN-SID: WYIWNZI5MCISICJHBGLJZUBLEGFTCGXLLMNVBSISICI2IL0=
X-MAILGUN-VARIABLES: {"MY_VAR_1": "MAILGUN VARIABLE #1", "MY-VAR-2": "AWESOME"}
DATE: FRI, 03 MAY 2013 18:26:27 +0000
SENDER: BOB_USER_ID@AWESOME_WORKFLOWS.MAILGUN.ORG
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520--
                                
                            

Ces quatre étapes vous aideront à configurer un webhook complet, mais pour en tirer parti, vous devrez le déclencher et en apprendre davantage sur les paramètres d’événement.

Comme expliqué ci-dessus, webhooks sont déclenchés par des événements spécifiques. Dans le domaine de l’email, ces événements incluent les ouvertures, les clics, les demandes de désinscription et d’autres événements liés à la livraison d’emails. Voici une répartition complète des événements Mailgun qui peuvent déclencher un webhook :

• Ouverture : cet événement se produit chaque fois qu’un destinataire ouvre un message. Le suivi des ouvertures est activé en utilisant les paramètres O:TRACKING ou O:TRACKING-OPENS lors de l’envoi d’un message.
• Clic : cet événement suit chaque fois qu’un destinataire clique sur des liens dans un message email. Activez le suivi des clics en utilisant les paramètres O:TRACKING ou O:TRACKING-CLICKS lors de l’envoi d’un message. Comme pour les ouvertures, les enregistrements CNAME appropriés doivent être inclus dans le DNS de l’utilisateur.
• Désinscription : cet événement se produit lorsqu’un destinataire clique sur le lien « désinscription » dans un message. Vous devrez utiliser le suivi des désinscriptions de Mailgun pour recevoir ces informations.
• Plainte pour spam : tous les FAI ne prennent pas en charge les notifications de boucle de rétroaction (« FBL ») pour les plaintes pour spam, mais vous devez vous assurer d’obtenir les données de tous ceux qui le font.
• Rebond : un message email est considéré comme un « rebond » s’il est rejeté par le serveur SMTP du destinataire. Ceux-ci sont souvent classés comme rebonds permanents ou temporaires comme suit :
  • Échec permanent (« rebond permanent ») : le destinataire est introuvable, et le serveur de messagerie du destinataire indique qu’il n’existe pas. L’application doit cesser de tenter la livraison à des destinataires non valides après un échec permanent.
  • Échec temporaire (« rebond temporaire ») : l’email n’est pas livré en raison d’un problème temporaire, tel qu’une boîte de réception pleine. Les applications peuvent répondre de manière programmatique aux échecs temporaires en réessayant un nombre défini de fois avant de supprimer l’adresse du destinataire de la liste.
• Livré : une livraison réussie se produit lorsque le serveur de messagerie du destinataire répond qu’il a accepté le message. En fonction de l’événement, les webhooks peuvent livrer une variété de paramètres pour aider à identifier et décrire le message en question. Des scripts peuvent ensuite extraire et analyser ces données. Les paramètres courants incluent :
  • Événement
  • Destinataire
  • Domaine d’envoi
  • En-têtes du message
  • Détails d’identification du destinataire : pays, région, ville, appareil, client de messagerie et système d’exploitation

Selon le service d’emailing, d’autres paramètres peuvent inclure des variables personnalisées, des balises et des noms de campagne, ainsi que des identifiants d’authentification ou d’utilisateur, entre autres. De plus, certains événements offrent plus de détails, comme une URL cliquée ; une raison ou une description pour un événement négatif, ou des codes spéciaux fournissant des détails d’événement spécifiques.

Une URL de réception doit être publique. Pour garder le contenu sécurisé, les webhooks doivent inclure un horodatage de signature et un jeton pour créer une table de hachage. Une table de hachage est simplement un moyen de stocker des éléments avec des identifiants. La table de hachage utilise également une clé API pour vérifier que les données proviennent bien du service d’emailing de l’équipe de développement. Vous devez programmer votre application pour vérifier cette table de hachage et la comparer à celle du service d’emailing, puis n’autoriser la requête POST que si elle correspond.

Pour vérifier que le webhook provient de son service d’emailing, vous devez lier les valeurs de l’horodatage et du jeton, encoder la chaîne résultante avec l’algorithme HMAC (en utilisant la clé API fournie par le service d’emailing comme clé et le mode de hachage SHA256), et comparer le résultat hexadécimal à la signature. De plus, vous pouvez mettre en cache la valeur du jeton localement et refuser d’honorer toute autre requête avec le même jeton. Cela empêchera les pirates informatiques d’utiliser le jeton pour répéter ou détourner des actions.

Le code d’état que vous renvoyez (par exemple, 200 OK) indique à l’expéditeur si le webhook a été traité avec succès. Surveillez toujours ces réponses pour garantir la résilience. Un autre niveau de sécurité consisterait à vérifier l’horodatage pour confirmer que la tentative POST a été effectuée dans un certain laps de temps.

Voici un exemple de code Python utilisé pour vérifier la signature d’un webhook :

                                

                                    import hashlib 
import hmac 

def verify(api_key, token, timestamp, signature): 
    message = f"{timestamp}{token}" 
    expected_signature = hmac.new( 
        key=api_key.encode(), 
        msg=message.encode(), 
        digestmod=hashlib.sha256 
    ).hexdigest() 
    return signature == expected_signature
                                
                            

Vous trouverez des informations complètes et du code sur la création et la suppression de différents types de webhooks dans notre documentation, mais nous avons inclus quelques exemples courants ci-dessous. Découvrez-les !

Vous pouvez utiliser notre API pour créer un nouveau webhook :

                                

                                    POST /domains//webhooks
                                
                            

Ou en mettre un à jour :

                                

                                    PUT /domains//webhooks/
                                
                            

Alternativement, vous pouvez facilement supprimer un webhook existant :

                                

                                    DELETE /domains//webhooks/
                                
                            

De plus, pour obtenir des informations sur vos webhooks, vous pouvez obtenir des détails sur n’importe quelle URL de webhook :

                                

                                    GET /domains//webhooks/
                                
                            

Bien sûr, si nous donnions des exemples de toutes les façons dont vous pouvez utiliser notre API pour créer et optimiser vos webhooks, nous pourrions y passer la journée. Le fait est que vous pouvez faire à peu près tout ce que vous voulez (nous promettons de ne pas le dire à votre mère).

Bien qu’il existe plusieurs méthodes pour accéder aux données générées par la livraison d’emails, y compris les tableaux de bord des services d’emailing et les appels d’API, simplifiez-vous la vie et ajoutez quelques webhooks pour faciliter les choses : ils constituent le moyen le plus flexible et le plus efficace de collecter des données granulaires sur les messages email.

Plutôt que d’extraire des données de votre service d’emailing, choisissez de recevoir des données push en continu liées à vos emails en temps réel. Mailgun facilite l’utilisation des webhooks, ce qui simplifie la tâche des équipes qui utilisent ces informations en temps réel pour prendre des décisions concernant les campagnes d’emailing actuelles et futures sur différentes applications et différents services web. C’est génial, non ?

Vous savez ce qui est aussi génial ? Plus d’informations sur les webhooks. Pour obtenir des informations simples et détaillées sur la façon d’utiliser les webhooks avec Mailgun, consultez notre documentation sur webhooks. Pour des analyses plus approfondies de ce type, inscrivez-vous à notre newsletter, les webhooks ne sont pas la seule chose qui peut vous apporter des données granulaires.

Auteur·trice: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!