Utilisation des Webhooks

Introduction

Le fonctionnement des webhooks est assez simple : dès qu'un événement ou un changement d'état a lieu sur un email (retour bounce, ouverture, clic, ...), on envoie une requête HTTP contenant en POST les informations de l'email en question, vers une URL donnée. Les webhooks servent donc à notifier des scripts externes qu'un événement a eu lieu.

Les webhooks offrent de nombreuses possibilités.

1. Confirmer l'ouverture d'un email

2. Identifier les adresses emails provoquant un retour bounce dans votre système

3. Traiter facilement vos emails de l'envoi à la lecture grâce à l'ajout de paramètre

4. ...

Ajout d'un webhook

Pour utiliser les webhooks, il faut au préalable ajouter votre url recevant l'appel au sein de Sarbacane. Pour cela, suivez cette procédure ( https://www.sarbacane.com/extensions/webhook/ )

Voici la liste des évenements disponibles et leurs descriptions

Traitement des retours

Chaque événement ayant eu lieu sur un email (délivré, ouvert, cliqué) donne lieu à un appel vers l'url fournie. Ainsi si l'email est ouvert plusieurs fois, vous recevez le même nombre de fois l'appel à votre URL.

Les retours sont effectués au format JSON et sont passés en POST à l'adresse communiquée.

Lors de l'appel, nous attendons une réponse HTTP 2XX afin de confirmer que l'URL fournie est bien accessible et que la transmission des données est possible. En cas d'échec, nous retentons à 10 reprises avant de cesser tout appel.

Voici des exemples de scripts permettant de récupérer les appels.

Enveloppe retour

Open

{
    "email" : "user@email.com",
    "campaignId" : "vdsioBFBFDS15dsBSGSD",
    "sendId" : "feizjfsVGVGRS55grgrs444",
    "subject" : "Test Déploiement Manager",
    "from" : "user@email.com",
    "operatingSystem" : "LINUX",
    "language" : "en-US,en;q=0.5",
    "browser" : "FIREFOX4 48.0",
    "webmail" : "Unknown”,
    "date" : "2016-08-11 T 12:25:18.889Z",
    "type" : "open"
}
                    

Click

{
    "email" : "user@email.com",
    "campaignId" : "vdsioBFBFDS15dsBSGSD",
    "sendId" : "feizjfsVGVGRS55grgrs444",
    "subject" : "Test Déploiement Manager",
    "from" : "user@email.com",
    "operatingSystem" : "LINUX",
    "language" : "en-US,en;q=0.5",
    "browser" : "FIREFOX4 48.0",
    "webmail" : "Unknown",
    "url" : "http://www.google.com”,
    "date": "2016-08-11 T 12:25:18.889Z",
    "type" : “click"
}
                    

Delivered

{
    "email" : "user@email.com",
    "campaignId" : "vdsioBFBFDS15dsBSGSD",
    "sendId" : "feizjfsVGVGRS55grgrs444",
    "subject" : "Test Déploiement Manager",
    "from" : "user@email.com",
    "date" : "2016-08-11 T 10:55:56.128Z",
    "type" : “delivered"
}
                    

Softbounce

{
    "email" : "user@email.com",
    "campaignId" : "vdsioBFBFDS15dsBSGSD",
    "sendId" : "feizjfsVGVGRS55grgrs444",
    "subject" : "Test Déploiement Manager",
    "from" : "user@email.com",
    "smtpDescription" : "Read timed out",
    "category" : "DEFAULT_SOFTBOUNCE",
    "returnCode" : -1,
    "date" : "2016-08-11 T 10:52:31.072Z",
    "type" : "soft_bounce"
}
                    

Hardbounce

{
    "email": "user@email.com",
    "campaignId": "vdsioBFBFDS15dsBSGSD",
    "sendId": "feizjfsVGVGRS55grgrs444",
    "subject": "test",
    "from": "user@email.com",
    "smtpDescription": "550 5.1.1 user unknown (UserSearch)",
    "category": "BAD_MAILBOX",
    "returnCode”: 550,
    "date": "2016-08-11 T 12:25:18.889Z",
    "type": "hard_bounce"
}
                    

Description de chacun des éléments

email :	adresse email du destinataire
campaignId :	identifiant de la campagne
sendId :	identifiant de l’envoi. dans le cas d’un split, le campaignId sera le même mais le sendID correspondra au send A, B ou C
subject :	objet de l'email
from :	expéditeur de l'email
operationsSystem:	pour les ouvertures et les clics, correspond au système d'exploitation
language :	pour les ouvertures et les clics, correspond à la langue de l’OS ou du navigateur
browser :	pour les ouvertures et les clics, correspond au moyen utilisé pour lire l’email soit une application de messagerie soit un navigateur
webmail :	pour les ouvertures et les clics, si l’email a été lu depuis un webmail
url :	dans le cas d’un clic, correspond au lien cliqué
type :	type d’evenements: delivered, open, click, hard_bounce, soft_bounce
date :	date de l’événement au format UTC
smptDescription :	pour les hard et soft bounces, retour SMTP effectué par le serveur de messagerie distante
returnCode :	pour les hard et soft bounces, code retourné
category :	pour les hard et soft bounces, type de soft ou hard bounce
whId :	si cette colonne est présente dans la liste des destinataires, alors nous vous renvoyons l’information contenue dans cette colonne

Mode hors connexion

Vous avez la possibilité sur Sarbacane de lire les données du webhook grâce à un JSON stocké sur le poste du client en mode hors connexion. vous n'aurez la possibilité que de consulter les données mais en aucun cas écrire dessus.

Utilisation d'un id externe

Si vous voulez récupérer simplement un identifiant utilisé sur votre système d'information, il vous suffit de renseigner ces informations dans une colonne que vous nommerez « whId » . Ce nom de colonne imposé "whId" est obligatoire pour utiliser l'id externe qui va transiter lors des retours JSON.