Consommation d'événements à l'aide de webhooks

Le contenu de cette page s'applique uniquement à SaaS. Pour recevoir les données utiles des événements via un appel POST, le serveur webhook doit effectuer certaines actions.

Les actions sont les suivantes :
  • Valider le jeton Oauth fourni.
    • Si le jeton a expiré ou n'est pas valide, il faut répondre avec le code de réponse 40x approprié.
    • Si le jeton fourni est valide, stockez le message de manière à ce qu'il n'y ait pas de risque de perte de données. Il est suggéré de stocker le message en l'écrivant dans un sujet Kafka, une file d'attente JMS, un système de fichiers ou une base de données.
  • Répondre à l'appel POST par un message 200 une fois que les données sont persistées d'une manière ou d'une autre.
Si la validation des données est nécessaire, il est fortement recommandé de demander à l'étape suivante d'effectuer toute validation requise plutôt que de retarder une réponse rapide. Les délais de réponse peuvent être confondus avec des erreurs de temporisation, ce qui entraîne une nouvelle publication des données. Cela peut avoir un effet en cascade : des messages sont publiés à plusieurs reprises parce que le serveur ne répond pas rapidement, ce qui ralentit encore plus le temps de réponse du webhook.

Lors de la mise en œuvre du serveur webhook, vous devez accorder une attention particulière au temps de réponse du webhook. Toute demande qui ne reçoit pas de réponse dans les 5 secondes est considérée comme ayant échoué et est réessayée. Si le message retenté continue d'échouer pour une raison quelconque, le système considère qu'il s'agit d'un échec de livraison de l'événement et la charge utile est placée dans la file d'attente de traitement des événements échoués.

Si votre webhook répond par un code d'erreur indiquant que le jeton a expiré (401), nous tenterons de générer et d'utiliser un nouveau jeton, à moins que la génération d'un jeton valide n'ait déjà échoué. Dans ce cas, nous acheminerons l'événement vers la file d'attente de traitement des événements défaillants.

Le système reconnaît que le serveur Oauth fourni n'est probablement pas dimensionné pour recevoir le même volume de demandes que le serveur webhook. Pour réduire le nombre d'appels au serveur Oauth, le système tente de rafraîchir le jeton Oauth environ 30 minutes avant son expiration.

Vous pouvez fournir la durée du jeton de deux façons :
  • Lorsque les webhooks sont embarqués, vous pouvez indiquer la validité du jeton en nombre d'heures. En cas de modification de la validité, le serveur doit être mis à jour avec la nouvelle durée.
  • Vous pouvez inclure la durée du jeton en secondes dans le champ expires_in du corps de la réponse Oauth. Cela permet au système de calculer la date d'expiration du jeton à chaque fois qu'il est généré et de modifier la durée du jeton.
    Note: Il est recommandé que les jetons générés durent au moins une heure.