Passer au contenu principal
Vérifiez chaque requête de webhook d’intégration avant de lui faire confiance. Qwairy signe chaque tentative avec le secret de l’endpoint ; une signature valide montre donc que la requête vient de Qwairy et que le corps n’a pas été modifié. Ne vous fiez pas à la place à un jeton intégré à l’URL de l’endpoint. Chaque clé de l’équipe qui peut lire ses webhooks, clés en lecture seule comprises, reçoit l’URL complète.

Fonctionnement de la signature

L’en-tête X-Qwairy-Signature est sha256= suivi du HMAC-SHA256 hexadécimal, calculé avec votre secret de signature, de cette chaîne :
  • Utilisez les octets bruts du corps, avant tout parsing JSON. Un corps parsé puis resérialisé produit une signature différente.
  • X-Qwairy-Timestamp est l’heure Unix en secondes à laquelle cette tentative a été signée. Chaque nouvelle tentative est signée à nouveau avec un nouvel horodatage.
  • Comparez en temps constant.
  • Rejetez les requêtes dont l’horodatage s’écarte de plus de 5 minutes de votre horloge. Cela limite le rejeu d’une requête interceptée.

Vérifier votre code avec un vecteur de test

Cet exemple synthétique vous permet de valider votre implémentation. Il utilise le secret synthetic-signing-secret et l’horodatage 1793610000.
La tolérance sur l’horodatage rejette cet exemple avec une horloge réelle ; passez donc un « maintenant » fixe dans votre test.

Node.js

Utilisez-la avec un parseur de corps brut, par exemple dans Express :

Python

Utilisez-la avec le corps brut, par exemple dans Flask :

Renouveler le secret

Après Renouveler le secret de signature, l’en-tête X-Qwairy-Signature porte deux valeurs séparées par une virgule pendant 24 heures. La première est signée avec le nouveau secret et la seconde avec l’ancien :
Les deux exemples ci-dessus découpent l’en-tête et acceptent la requête dès qu’une valeur correspond au secret que vous détenez. Pour renouveler le secret sans perdre d’événements :
  1. Renouvelez le secret et conservez la nouvelle valeur.
  2. Déployez le nouveau secret sur votre récepteur. Les requêtes continuent de passer pendant la période de chevauchement, quel que soit le secret que vous détenez.
  3. Après 24 heures, les requêtes portent de nouveau une seule signature.
previousSecretExpiresAt dans l’endpoint indique la fin du chevauchement.

Dépannage

  • Toutes les requêtes échouent. Vérifiez que vous signez le corps brut et non un corps resérialisé, et qu’aucun middleware ne le modifie avant votre gestionnaire.
  • Seules certaines requêtes échouent. Vérifiez l’horloge de votre serveur par rapport à la tolérance de 5 minutes.
  • Une requête échoue après un renouvellement. Vérifiez que vous utilisez le nouveau secret et que vous comparez chaque valeur de l’en-tête.