Webhooks
Rotation du secret de signature
Effectuez une rotation sûre de votre secret de signature de webhook avec une fenêtre de grâce de double signature de 24 heures
POST
Vue d’ensemble
Ayrshare signe chaque livraison de webhook avec un HMAC-SHA256 de la charge utile, en utilisant votre secret de signature comme clé, afin que votre récepteur puisse confirmer qu’une livraison provient bien d’Ayrshare. Consultez Sécurité des webhooks pour savoir comment fonctionne la vérification. La rotation de votre secret de signature vous permet de le remplacer selon un calendrier régulier, ou immédiatement si vous soupçonnez qu’il a été exposé. Pour rendre la rotation sûre, Ayrshare ouvre une fenêtre de grâce de 24 heures après chaque rotation pendant laquelle les livraisons sont signées avec à la fois votre secret précédent et votre nouveau secret. Cela vous permet de mettre à jour votre récepteur à votre propre rythme sans manquer ou rejeter la moindre livraison — le même modèle que celui utilisé par Stripe et GitHub.Le secret de signature est à l’échelle du profil : il y a un secret par User Profile (UID),
et il signe toutes les actions de webhook que ce profil a enregistrées. Il n’existe pas
de secret de signature par action — définir ou faire tourner le secret le modifie pour toutes
les actions de ce profil en même temps.
Rotation depuis le tableau de bord
Vous pouvez définir ou faire tourner votre secret de signature depuis la page Webhooks du tableau de bord développeur. Le panneau Signing Secret apparaît au-dessus de votre liste de webhooks une fois que le profil possède au moins un webhook enregistré.1
Ouvrez le panneau Signing Secret
Rendez-vous sur la page Webhooks. Si aucun secret n’est encore configuré, le panneau affiche No signing secret configured avec un bouton Set Signing Secret. Si un secret est déjà configuré, il affiche Signing secret configured avec un bouton Rotate.
2
Définir ou effectuer la rotation
Cliquez sur Set Signing Secret (première fois) ou Rotate (secret existant). Une fenêtre modale s’ouvre avec un secret fort, généré aléatoirement, pré-rempli et révélé. Vous pouvez le Copy, en Regenerate un nouveau, ou basculer sur paste my own pour fournir votre propre valeur.
3
Confirmer
Copiez le secret dans un endroit sûr — il n’est affiché qu’une seule fois et ne peut plus jamais être récupéré depuis l’UI — puis confirmez pour soumettre. Un toast de succès apparaît et le panneau se met à jour.
4
Mettez à jour votre récepteur
Lors d’une rotation (et non d’une première définition), le panneau affiche un indicateur de fenêtre de grâce active et le bouton Rotate est désactivé jusqu’à la fermeture de la fenêtre. Vous disposez de 24 heures pour déployer le nouveau secret sur votre récepteur.
Rotation via l’API
Effectuez la rotation (ou la définition) du secret de signature en un seul appel. Cela crée un nouveau secret, repointe la référence du secret du profil vers lui et — lorsqu’un secret existant était en place — enregistre le secret remplacé en tant que secret précédent avec une expiration dans 24 heures.Paramètres d’en-tête
Paramètres du corps
string
requis
La nouvelle valeur du secret de signature. Toute chaîne non vide est acceptée. Nous recommandons une valeur aléatoire longue et à haute entropie (par exemple, 32 octets aléatoires encodés en base64url).
secret en clair n’est jamais renvoyé dans la réponse et n’est jamais enregistré dans les journaux. La réponse contient le refId destiné au client (un hachage de l’UID), jamais l’UID lui-même. L’en-tête Profile-Key est optionnel et limite la rotation à un seul User Profile pour les comptes multi-profils.
Un secret manquant ou vide renvoie une erreur mappée (code: 101, « Missing/incorrect parameter ») avec un statut HTTP 400, et aucune modification n’est apportée à votre secret actuel. Une première définition via l’API (sans secret existant) crée le secret sans secret précédent enregistré et sans fenêtre de grâce.
Procédure de rotation sûre
Grâce à la fenêtre de grâce de 24 heures, aucun ordre d’opérations n’est requis — votre récepteur continue de fonctionner pendant toute la durée. La séquence recommandée est la suivante :1
Effectuez la rotation du secret
Effectuez la rotation depuis le tableau de bord ou via l’API. Ayrshare commence immédiatement à signer les livraisons avec à la fois votre secret précédent et votre nouveau secret.
2
Mettez à jour votre récepteur
Dans les 24 heures, déployez le nouveau secret sur votre récepteur de webhook afin qu’il vérifie par rapport à la nouvelle valeur.
3
Laissez la fenêtre se fermer
Après 24 heures, Ayrshare efface automatiquement le secret précédent et signe uniquement avec le nouveau secret. Aucune autre action n’est nécessaire de votre côté.
Vérification des signatures pendant la fenêtre de grâce
En dehors d’une fenêtre de grâce, les livraisons signées portent les en-têtes standard (voir Sécurité des webhooks) :X-Authorization-Content-SHA256-V2 liste les deux signatures, la signature actuelle en premier, séparées par une virgule :
X-Authorization-Content-SHA256 est inchangé : il porte toujours le HMAC unique
du secret actuel, pour la rétrocompatibilité. Les doubles signatures n’apparaissent que
dans le nouvel en-tête X-Authorization-Content-SHA256-V2.X-Authorization-Content-SHA256-V2 est préfixée par un tag de schéma. v1= désigne une signature HMAC-SHA256, calculée exactement comme X-Authorization-Content-SHA256. L’en-tête -V2 est toujours présent lorsqu’une livraison est signée — il porte au moins v1=<current-sig> — vous pouvez donc vous y fier comme un contrat de récepteur stable.
Pour vérifier une livraison pendant (ou en dehors d’)une rotation :
1
Calculez le HMAC
Calculez le HMAC-SHA256 du corps de requête brut en utilisant le secret de signature configuré localement.
2
Comparez à chaque signature listée
Lisez
X-Authorization-Content-SHA256-V2, divisez-le sur les virgules, retirez le préfixe v1= de chaque valeur, et acceptez la livraison comme authentique si votre HMAC calculé correspond à n’importe quelle signature v1= listée.v1=<previous-sig>, tandis qu’un récepteur mis à jour vers le nouveau secret correspond à v1=<current-sig> — les deux réussissent pendant toute la durée de la fenêtre.
Exemple de vérification côté récepteur
Node.js
