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 notre adresse IP : 185.183.140.195.

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.
Lors de ces nouvelles tentatives, nous avons un timeout d’accès à l’URL distante adaptatif :

• 1er au 9 essais : Timeout de 2.5s
• 10 au 19 essais : Timeout de 4.5s
• 20 au 29 essais : Timeout de 6.5s
• 30 au 39 essais : Timeout de 8.5s
• 40 au 48 essais : Timeout de 11s

Les données de la requête HTTP POST seront au format url-ify (encodé dans l’URL)  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:

• Un webhook global recevant l’intégralité des webhooks (utilisateurs + courriers).
• Un webhook spécifique à un courrier.

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 :

• id_user : l’identifiant utilisateur AR24, rattaché à votre API.
• event : slug décrivant l’évènement reçu.

Vous retrouverez dans notre documentation la liste des évènements : https://developers.ar24.fr/doc/#post-user-webhook.

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 :

• id_mail : l’identifiant du courrier.
• new_state : slug décrivant le nouveau statut du courrier.

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

• proof_url : lien pour télécharger la preuve associée au nouveau statut.

Vous retrouverez dans notre documentation la liste des évènements et des données associées : https://developers.ar24.fr/doc/#post-registered-letter-webhook.

5. Consulter l'historique de votre Webhook

Pour vous aider dans votre intégration ou pour réaliser du monitoring, vous avez la possibilité de récupérer sous forme de liste l’historique des notifications envoyées à votre webhook. Vous y retrouverez les informations contenues dans la requête ainsi que l’url appelée, le nombre de tentatives, la date de dernière tentative et son statut.

Vous avez la possibilité d’ajouter des filtres pour affiner votre recherche pour un utilisateur ou un courrier donné, et sur une période donnée.

Vous retrouverez toutes les informations dans notre documentation : https://developers.ar24.fr/doc/#get-list-webhook-calls.