Obtenez le statut de vos courriers en temps réel avec un Webhook

Récupérez l’évolution du statut de vos courriers et de vos utilisateurs en temps réel en intégrant un système de Webhook directement via l’API.

1. Qu’est ce qu’un Webhook ?

Dans le cadre de l’API AR24, vous pourriez vouloir être notifié de l’ouverture d’un courrier pour en informer l’expéditeur. Vous pouvez récupérer le statut de votre courrier à l’aide de la route /api/mail en fournissant l’identifiant du courrier, mais vous n’êtes pas capable d’obtenir le changement de statut du courrier en temps réel. C’est à ce moment que le système de Webhook rentre en jeu.

Un Webhook est un rappel HTTP (callback) permettant de déclencher une action suite à un événement.
Cela consiste en une URL vous appartenant (par exemple https://votrelogiciel.fr/webhookAR24) qui sera appelée par AR24 à la suite d’une modification de statut d’un courrier ou d’un utilisateur pour vous tenir informé en temps réel.

2. Comment configurer mon Webhook ?

Dans un premier temps, vous devez préparer de votre côté une adresse sur laquelle sera effectuée la requête HTTP contenant les données à traiter.
Veuillez vous assurer d’avoir fait le nécessaire pour accepter les requêtes en provenance de nos adresses IPs : 141.138.159.79/32 ; 141.138.159.174/32.

Un webhook repose sur une communication de données entre deux services, ainsi nous attendons en retour un code HTTP 200 pour nous assurer que vous ayez bien réceptionné les informations contenu dans la requête.
Dans le cas contraire, nous effectuerons un nouvel envoi de la requête toutes les 15 minutes jusqu’à un maximum de 48 tentatives.

Les données de la requête HTTP POST seront au format form-data  et la structure sera présentée par la suite. Il est possible en nous contactant (api@ar24.fr) d’activer une option pour recevoir les données au format JSON si vous préférez.

Il existe au sein de notre API deux types de webhook qui seront détaillés par la suite:

Pour configurer votre webhook global, vous pouvez soit nous transmettre l’url à utiliser par email en contactant api@ar24.fr, soit la renseigner vous-même depuis votre espace administrateur API si celui-ci est configuré.

3. Récupérer les évènements liés aux utilisateurs

La première catégorie d’évènement que vous pouvez recevoir en utilisant un webhook concerne les utilisateurs.
Ces évènements permettent de vous notifier, par exemple, quand un utilisateur accepte de se rattacher à votre API, ou encore s’il décide de révoquer ses identifiants depuis son espace client sur notre site.

Vous recevrez ces évènements sur votre webhook global avec la structure suivante :

Vous retrouverez dans notre documentation la liste des évènements : https://developers.ar24.fr/documentation/#api-WebhookGroup-webhook_user_desc.

4. Suivre l’évolution de vos courriers

La seconde catégorie d’évènement concerne les courriers envoyés depuis votre API.
Ces évènements vont vous permettre de suivre l’évolution du statut d’un courrier ou d’une demande de consentement, et notamment d’être informé qu’une action est attendue par l’expéditeur dans le cas d’une demande de modification de coordonnées.

Vous recevrez ces évènements sur votre webhook global, à moins que vous n’ayez renseigné un webhook spécifique à la création du courrier dans le champs « webhook » (Voir notre documentation).
Un webhook spécifique vous permet d’associer une URL personnalisée pour chaque courrier, pouvant par exemple être utilisé pour lier les évènements du courrier à un identifiant interne : https://votrelogiciel.fr/webhookAR24/identifiant_interne .

La structure des données reçu est la suivante :

En fonction du statut du courrier, vous recevrez d’autres données avec comme par exemple :

Vous retrouverez dans notre documentation la liste des évènements et des données associées : https://developers.ar24.fr/documentation/#api-WebhookGroup-webhook_ar_desc.

Vous ne trouvez pas votre réponse ? Contactez nous