Webhooks HMAC : relier DEKROSH à HubSpot en sécurité
Le flux exact : votre middleware vérifie la signature DEKROSH, refuse les rejouements, puis appelle l'API HubSpot.
Cet article a été rédigé avec l’assistance d’une intelligence artificielle et publié sous la responsabilité éditoriale de DEKROSH. Les illustrations de ce blog sont générées par IA. Les sources officielles utilisées sont indiquées dans le texte.
DEKROSH envoie un webhook sortant vers une URL que vous contrôlez. HubSpot ne vérifie pas nativement la signature propre à DEKROSH : votre endpoint doit d'abord authentifier la requête, puis appeler l'API HubSpot avec les identifiants prévus par votre intégration.
Le flux recommandé
- DEKROSH sérialise le corps JSON et calcule une signature HMAC-SHA256 avec le secret du webhook.
- Votre middleware reçoit le corps brut et les en-têtes.
- Il vérifie l'horodatage et la signature avant de parser ou transformer le JSON.
- Il déduplique l'événement grâce à
X-DEKROSH-Delivery-Id. - Après validation seulement, il crée ou met à jour le contact dans HubSpot via l'API autorisée.
Format de la signature DEKROSH
L'en-tête X-DEKROSH-Signature suit le format t=<timestamp>,v0=<hex>. La valeur signée est la concaténation de l'horodatage, d'un point et du corps brut. Le calcul utilise HMAC-SHA256.
La comparaison doit être effectuée en temps constant. Refusez un horodatage trop ancien ; l'implémentation DEKROSH utilise une tolérance de cinq minutes. Ne reconstruisez pas le JSON avant la vérification, car un espace ou un ordre de propriété différent modifierait la signature.
Gérer les doublons et les erreurs
Une livraison peut être réessayée après une erreur. Enregistrez l'identifiant de livraison avant l'appel au CRM et rendez le traitement idempotent. Retournez un code de succès uniquement lorsque l'événement est durablement accepté ; pour un traitement long, placez-le dans une file puis répondez.
Protéger les secrets et les données
- Conservez le secret HMAC et le jeton HubSpot dans un gestionnaire de secrets.
- N'écrivez pas le corps complet dans les logs s'il contient des coordonnées ou une transcription.
- Faites tourner le secret selon une procédure qui accepte temporairement l'ancien et le nouveau.
- Limitez les propriétés envoyées à HubSpot à celles nécessaires au scénario.
Ne pas confondre deux signatures
La documentation HubSpot sur ses propres webhooks décrit les événements envoyés par HubSpot vers une application. Ici, la direction est différente : DEKROSH envoie vers votre middleware. Les mécanismes doivent être implémentés séparément.
