Bonnes pratiques
Vérifiez chaque signature
N’agissez jamais sur un webhook que vous n’avez pas vérifié. Rejetez les requêtes dont la signature ne correspond pas ou dont le timestamp a plus de 5 minutes.
Répondez vite, travaillez ensuite
Renvoyez 2xx dès que la signature est vérifiée et l’event enregistré, puis traitez-le dans une
tâche de fond. Votre handler doit répondre en moins de 10 secondes ; un traitement lent dans la
requête devient un délai dépassé, puis une nouvelle tentative, puis un doublon.
Dédupliquez sur l’ID de l’event
Un même event peut être livré plusieurs fois (nouvelles tentatives, renvois manuels). Conservez les
ID des events traités (X-Skoup-Event-Id ou l’id du corps) et ignorez ceux que vous connaissez
déjà.
Ne comptez pas sur l’ordre
L’ordre d’arrivée des livraisons n’est pas garanti. Quand l’ordre compte, comparez les timestamps
created, ou relisez l’état courant de l’objet par l’API.
Abonnez-vous à ce que vous utilisez
Choisissez les types d’events que votre intégration traite plutôt que *. Vous recevez moins de
trafic, et les nouveaux types d’events ajoutés à Skoup ne surprendront pas votre handler.
Tolérez les champs inconnus
Les payloads s’enrichissent avec le temps — de nouveaux champs sont ajoutés au sein de la v1. Ignorez les champs que vous ne connaissez pas au lieu d’échouer.
Tester en local
Skoup ne livre qu’à des URL HTTPS publiques. Pour recevoir des events sur votre machine, ouvrez un tunnel vers votre serveur local et déclarez l’URL du tunnel comme endpoint de test :
ngrok http 3000
# Forwarding https://4f2a-81-23-45-67.ngrok-free.app -> http://localhost:3000Utilisez ensuite Envoyer un event de test sur l’endpoint, ou créez une tâche avec une clé de
test : l’event task.created correspondant arrive sur votre machine en quelques secondes.