Même API, nouvelles astuces : recevez des notifications d’événements juste à temps avec les webhooks

Nous avons donc eu quelques réflexions en travaillant sur cette mise à jour de l’API, et vous les avez peut-être eues vous aussi :

1. Les webhooks, c’est génial ! Tout le monde devrait les utiliser.
2. Extraire les données d’envoi directement de mes messages permet de gagner du temps.

Honnêtement, l’API de webhooks de Mailgun existe depuis longtemps maintenant. Mais avec cette mise à jour, vous avez plus de choix pour communiquer avec nous et voir les détails de ce qui se passe avec vos messages.

Plongeons dans les détails.

Alors, en quoi consiste cette mise à jour ?

Mailgun peut vous aider à recevoir des notifications juste à temps afin que vous puissiez voir quand quelque chose s’est produit avec votre message. Vous avez le choix d’utiliser l’interrogation d’événements via l’Events API, ou de nous laisser vous pousser des événements via l’API de webhooks. Ces alertes ont les mêmes données que l’Events API et sont envoyées à votre ou vos URL par HTTP POST.

Désormais, vous obtenez

• Une charge utile « Application/JSON »
• Jusqu’à trois URL par événement
• Des données sur les types d’événements suivants :
  • opened – chaque fois qu’un utilisateur ouvre l’un de vos messages
  • clicked – chaque fois qu’un utilisateur clique sur un lien dans vos messages
  • unsubscribed – lorsqu’un utilisateur se désinscrit, que ce soit de tous les messages, d’une balise spécifique ou d’une liste de diffusion
  • complained – lorsqu’un utilisateur signale l’un de vos emails comme spam. Notez que les services d’emailing ne fournissent pas tous ce retour.
  • delivered – lorsque le serveur de messagerie du destinataire répond qu’il a accepté le message. 
  • permanent_fail – il y a plusieurs raisons pour lesquelles Mailgun cesse d’essayer de livrer des messages et les abandonne, notamment les rebonds permanents, les messages ayant atteint leur limite de tentatives, les adresses ayant fait l’objet d’une désinscription, d’un rebond ou d’un signalement antérieur, ou les adresses rejetées par un service d’emailing.
  • temporary_fail – lorsqu’un message est temporairement rejeté par un service d’emailing

L’avantage est que votre code pour la logique métier peut être utilisé pour l’une ou l’autre des options. La différence réside dans la façon dont vous vous connectez à Mailgun. Et comme chaque événement a son propre identifiant unique, s’il s’avère que votre point de terminaison http ne répond plus pour une raison quelconque, vous pouvez facilement extraire les événements et les trier à l’aide de cet identifiant unique. Bien sûr, nous recommandons toujours de traiter les webhooks de manière asynchrone afin que les pics d’événements ne posent pas de problème.

Voyons maintenant comment configurer un domaine avec le webhook « clicked ». Il s’agit en fait d’un processus en une seule étape que vous pouvez réaliser en configurant une ou plusieurs URL à l’aide de curl ou de votre langage de programmation préféré via notre API HTTP.

Par exemple, en utilisant la commande curl :

                                

                                    curl -s --user ‘api:YOUR_API_KEY’
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks
-X POST
-F id=clicked
-F url="https://api.your.domain.com/v1/mg/clicked"
-F url="https://api.your.domain.com/v2/mg/clicked"
-F url="https://api.partner.com/v1/you/clicked"
                                
                            

Ici, “id” doit être le nom du webhook (un seul webhook par requête) et “url” doit indiquer votre URL (jusqu’à trois URL par requête).

Et le message de réponse :

                                

                                    {

"message": "Webhook has been created",

"webhook": {

    "urls": [

         "https://api.your.domain.com/v1/mg/clicked",

         "https://api.your.domain.com/v2/mg/clicked",

         "https://api.partner.com/v1/you/clicked"

     ]

 }

}
                                
                            

Les données reçues sur votre ou vos URL devraient être :

                                

                                    {

  “signature”:    

  {

    "timestamp": "1529006854",

    "token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",

    "signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"

  }

  “event-data”:    

  {

    "timestamp": 1529006854.329574,

    "id": "DACSsAdVSeGpLid7TN03WA",

    "event": "delivered",

    "tags": [...],

    "user-variables": {...},

    "message": {

         "headers": {

             "message-id": "20180618211821.example.org"

          }

    },

    …

  }

}
                                
                            

La partie “event-data” est la même que ce que l’Events API renvoie et contient : l’horodatage de l’événement, l’identifiant unique de l’événement, le nom de l’événement, l’identifiant du message, vos balises et variables, etc. En tant que bonne pratique, n’oubliez pas de vérifier la partie “signature” (voir ici comment procéder).

Et c’est tout. Facile, non ?

Oui, c’est possible ! Si vous devez migrer votre application vers une nouvelle version, ou si vous devez envoyer des événements au site de votre partenaire, cela peut être fait pour un maximum de trois points de terminaison.

Si vous voulez voir à quoi ressemble votre événement ou si vous avez une question pour notre équipe de support, il est facile de configurer un webhook avec une URL temporaire vers notre corbeille de requêtes à l’adresse  http://bin.mailgun.net et de consommer des événements en même temps.

Voici un aperçu de ce qui se passe lors de l’utilisation d’une API de test également, en utilisant la commande curl suivante :

                                

                                    curl -s --user ‘api:YOUR_API_KEY’ \

https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/HOOK_NAME/test \

-X PUT \

-F url=YOUR_URL
                                
                            

Ici, “url” correspond à votre URL (une par requête) et “HOOK_NAME”  correspond à un nom de webhook (voir la liste ci-dessus – un par requête également).

Et le message de réponse :

                                

                                        {
    "code"   : null,
    "message": "{\"message\":\"Post received. Thanks!\"
    }
                                
                            

Ici, “code” indique le code HTTP reçu de votre côté (null signifie 200 OK) et “message” indique le corps HTTP reçu de votre côté ou le message d’erreur

Oui. Et tous les anciens webhooks devront être migrés vers cette nouvelle version. Le point de terminaison de l’ancienne API de webhooks est devenu en lecture seule à compter du 15 avril 2023, concluant un processus de dépréciation qui a commencé en mars 2022.

Les mises à jour de produits sont importantes, et en tant qu’entreprise d’email, nous sommes plutôt doués pour envoyer des mises à jour afin de vous tenir au courant. Vous voulez explorer le pourquoi et le comment de nos actions ? N’oubliez pas de vous inscrire à notre newsletter pour plus de contenu de ce type.

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!