Extension 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

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.