Webhooks

Concept

Un Webhook (également appelé web callback ou HTTP push API) est une méthode permettant à votre application d'être informée d'un événement en temps réel.

Par exemple, si vous envoyez un contrat pour signature et que vous devez être informé dès qu'il est signé.

Vous pourriez programmer une boucle qui interroge l'état du document toutes les 5 minutes pendant plusieurs jours jusqu'à ce que vous receviez une réponse indiquant que le document est signé. Cette approche est déconseillée, car elle gaspille beaucoup de ressources chaque fois que vous effectuez un appel à l'API sans raison valable.

Une meilleure approche consiste à configurer un webhook dans la console d'administration eZmax afin de surveiller un événement spécifique. Dans cet exemple, l'événement à surveiller est DocumentCompleted du module Ezsign. De cette façon, dès que le document est signé, une requête sera envoyée à votre serveur pour vous informer de l'événement qui vient de se produire.

Lorsque vous configurez eZmax pour vous informer des événements, vous devez fournir l'URL de votre serveur ainsi qu'une adresse courriel de secours. L'URL fournie doit utiliser HTTPS pour des raisons de sécurité.

Types de webhooks

Recherchez les indicateurs rouges contenant le mot EVENT dans la référence afin de voir les événements Webhook actuellement disponibles auxquels vous pouvez vous abonner. Si vous avez besoin d'un événement qui n'est pas disponible, veuillez envoyer une demande d'amélioration au support technique.

Important

• L'événement sera transmis à l'aide d'une requête POST.
• Votre serveur devra répondre avec un code de statut HTTP 200, 202 ou 204 afin d'indiquer à eZmax que vous avez accepté le message et que nous ne tenterons pas de le transmettre à nouveau. Si le serveur ne répond pas avec un code 200, 202 ou 204, le message sera envoyé à plusieurs reprises jusqu'à ce que toutes les tentatives soient épuisées.
• La réponse 200, 202 ou 204 doit être retournée en moins de 30 secondes, sinon un délai d'attente (timeout) se produira et l'événement sera envoyé de nouveau selon le calendrier de tentatives.
• Assurez-vous de sécuriser l'URL de réception de votre Webhook afin d'empêcher qu'une personne n'envoie des messages falsifiés à votre application. Vous pouvez le faire en fournissant un jeton sécurisé dans votre URL, par exemple ?token=mysecuretoken1234, ou en validant la signature du message Webhook.
• Le User-Agent de la requête sera Ezmax-Webhook.

Signature des requêtes

Vous pouvez activer la signature des requêtes dans la section de configuration des Webhooks. Cela ajoutera une couche de sécurité supplémentaire en ajoutant des en-têtes d'autorisation, de date, d'empreinte et de signature à chaque requête, que vous pourrez ensuite valider. Cette méthode permet d'authentifier la requête, de prévenir la falsification et d'empêcher les attaques par rejeu (replay attacks).

Les en-têtes HTTP suivants seront ajoutés à chaque requête :

• Ezmax-Authorization
• Ezmax-Date
• Ezmax-Fingerprint
• Ezmax-Signature

Vous pouvez en apprendre davantage sur la signature des requêtes dans la section Sécurité de la documentation. (Ajouter un lien?)

Tests

Dans le module d'administration eZmax, vous trouverez un bouton « Test » que vous pouvez utiliser autant de fois que nécessaire afin de tester facilement le code de votre serveur à l'aide d'un exemple d'événement.

Tentatives

eZmax tentera de transmettre l'événement à votre serveur immédiatement, mais effectuera plusieurs tentatives supplémentaires si votre serveur ne répond pas correctement pour une raison quelconque (voir le calendrier ci-dessous). Après l'épuisement de toutes les tentatives, l'événement sera transféré à l'adresse courriel de secours configurée, dans le même format que celui utilisé pour le webhook. Le courriel contiendra la requête JSON ainsi que les en-têtes HTTP dans le même format que celui utilisé pour le webhook. De cette façon, vous pourrez envoyer la requête à votre serveur à l'aide de Postman, de Curl ou d'un outil similaire.

Calendrier des tentatives de retransmission

Il s'agit du calendrier approximatif des tentatives de retransmission. Comme un délai d'attente de 30 secondes est appliqué à chaque tentative, il peut y avoir un délai cumulatif allant jusqu'à 3½ minutes.

INFO

Le tableau suivant s'applique uniquement aux événements automatiques réels. Les événements de test et les retransmissions manuelles ne sont tentés qu'une seule fois. En cas d'erreur ou de délai d'attente (timeout), une notification par courriel sera envoyée immédiatement.

Minutes après l'étape précédente	Minutes après l'événement	Méthode
N/A	0	HTTPS
1	1	HTTPS
5	6	HTTPS
15	21	HTTPS
15	36	HTTPS
15	51	HTTPS
15	66	HTTPS
0	66	Courriel

Rapport des tentatives échouées

Si vous ne recevez pas l'événement lors de la première tentative, des informations de débogage concernant chaque tentative précédente seront incluses dans le corps de l'événement. Vous pourrez voir l'horodatage de chaque tentative précédente ainsi que le code de retour renvoyé par votre serveur, ou une indication de délai d'attente (timeout) si votre serveur n'a pas répondu.