Les Webhooks

L'API RESTful d'envoi de courrier en ligne de MySendingBox utilise le fonctionnement des webhooks pour vous tenir au courant du statut de vos envois.

Après avoir défini une URL sur laquelle l'API devra poster des événements, vous serez en mesure de recevoir des évènements à propos de vos courriers.

Fonctionnement des webhooks

Les webhooks permettent de recevoir des notifications directement sur votre serveur lors d'événements spécifiques sur vos courriers.
Ils vous évitent ainsi de devoir constamment vérifier si un courrier a changé de statut. Vous pourrez ainsi savoir si une lettre a été envoyée, si elle a été reçue contre signature (pour un recommandé) ou encore si elle est retournée à l'expéditeur.

Pour recevoir des webhooks, vous devez fournir une URL qui accepte les requêtes POST.

Pour confirmer que vous avez bien reçu la notification, votre URL doit renvoyer un code HTTP 200. Si vous ne renvoyez pas de code 200, MySendingBox continuera à essayer de poster sur votre URL avec le rythme indiqué dans le tableau suivant.

Utilisez le débogueur disponible sur la page Webhooks du dashboard pour tester les différents événements possibles.

A noter que si plusieurs événements sont en attente, ils ne sont pas regroupés. L'objet letter sera toujours à la dernière version de la base de données.

Essai n°	Temps depuis le dernier essai
1	1 minute
2	5 minutes
3	30 minutes
4	1 heure
5	2 heures
6	6 heures
7	12 heures
8	24 heures

Sécurité

Il est recommandé d'utiliser une URL de webhook en HTTPS.
Vous devriez aussi ajouter une Basic Authentification pour protéger votre URL et éviter que d'autres personnes que MySendingBox postent sur votre URL de webhook.
Ajoutez simplement un username et un mot de passe à votre url comme ici :
https://username:password@yourendpointurl.com/webhooks

Scaling

Plus vous envoyez de courriers, plus vous recevez d'événements webhooks. Vérifiez que vous êtes en capacité d'absorber le trafic avant d'ajouter les webhooks à votre flow.

Suivi des recommandés

Quelques heures après l'envoi d'un recommandé avec ou sans accusé de réception via l'API, un numéro de suivi sera disponible dans la variable tracking_number de l'objet letter. Celui-ci vous sera notifié par le déclenchement de l'événement letter.sent.

Cependant, vous n'avez pas besoin de suivre vous-même votre envoi. MySendingBox vous notifiera de l'avancée de votre recommandé via l'événement letter.in_transit.

Un objet tracking_events sera aussi disponible dans l'objet letter. Celui-ci contient l'historique La Poste de l'acheminement de votre courrier.

Un événement letter.filing_proof sera envoyé lorsque la preuve de dépot sera disponible (sous objet filing_proof de votre objet letter).

Lors de la réception d'un recommandé par le destinataire l'événement letter.distributed sera déclenché.

manage_returned_mail

Si lors de la création de votre courrier vous avez sélectionné l'option manage_returned_mail : true alors la gestion des NPAI (N'habite Pas à l'Adresse Indiquée) ou des PND (Pli Non Distribué) sera géré par l'API.
Si un courrier n'a pas pu être distribué ce retour d'information interviendra généralement 10 à 15 jours après letter.sent.
L'évènement letter.wrong_address sera envoyé à l'url de webhook à cette occasion.

Listes des événements

Courrier

Nom de l'évènement	Condition d'envoi
letter.created	Déclenché lorsqu'une lettre est créée. Disponible pour ecopli, prioritaire, lr, lrar.
letter.accepted	Déclenché lorsqu'une lettre est acceptée par le système d'impression et d'envoi. Disponible pour ecopli, prioritaire, lr, lrar.
letter.filing_proof	Déclenché lorsqu'une lettre reçoit une preuve de dépot. L'objet letter contiendra maintenant une variable filing_proof contenant la preuve de dépot. Si postage_type est lr ou lrar : l'objet letter contiendra maintenant un tracking_number. Disponible pour lr lrar.
letter.sent	Déclenché lorsqu'une lettre est envoyée. Si postage_type est lr ou lrar : l'objet letter contiendra maintenant un tracking_number. Disponible pour ecopli, prioritaire, lr, lrar.
letter.error	Déclenché lorsqu'une lettre est en erreur. Cet évènement peut-être déclenché lors d'un refus du courrier par la Poste pour une adresse incorrecte ou pour un problème lors de l'impression du courrier. Disponible pour ecopli, prioritaire, lr, lrar.
letter.in_transit	Déclenché lorsqu'un Tracking event est disponible. Disponible pour lr, lrar.
letter.waiting_to_be_withdrawn	Déclenché lorsqu'une lettre est disponible au guichet pour être retirée par le destinataire. Disponible pour lr lrar.
letter.distributed	Déclenché lorsqu'une lettre est reçue par le destinataire. Disponible pour lr, lrar.
letter.returned_to_sender	Déclenché lorsqu'une lettre est retournée à l'expéditeur. Aucun autre événement ne sera déclenché après celui-ci. Disponible pour lr, lrar.
letter.wrong_address	Déclenché lorsqu'une lettre n'a pas pu être remise au destinataire car il n'habite pas à l'adresse indiquée (NPAI). Aucun autre événement ne sera déclenché après celui-ci. Disponible pour ecopli, prioritaire, lr, lrar si manage_returned_mail : true.
letter.delivery_proof	Déclenché lorsqu'une lettre reçoit un accusé de réception. L'objet letter contiendra maintenant une variable delivery_proof contenant l'accusé de réception.
letter.canceled	Déclenché lorsqu'une lettre est annulée. Disponible pour prioritaire, lr, lrar.