Vos récepteurs peuvent être déployés à des moments différents. Un chevauchement permet à un récepteur utilisant l'ancien secret et à un récepteur utilisant le nouveau secret d'authentifier la même livraison.
Continuez à vérifier les livraisons tout au long du déploiement afin qu'une requête provenant d'un attaquant ne puisse pas déclencher de traitement.
Que se passe-t-il quand j'effectue une rotation ?
Bird vous fournit un nouveau secret de signature. Déployez-le dans les 24 heures, pendant que Bird signe encore avec l'ancien secret.
Appelez rotateWebhookSecret pour votre endpoint. Enregistrez son secret, une chaîne non vide commençant par whsec_, car elle n'est renvoyée que dans cette réponse.
Bird signe chaque livraison avec les deux secrets pendant le chevauchement. L'en-tête webhook-signature contient des signatures séparées par des espaces, chacune commençant par v1,.
Un récepteur peut vérifier l'une ou l'autre signature à l'aide du secret correspondant. Terminez le déploiement dans les 24 heures, car l'ancien secret cesse de signer après cette fenêtre.
Que doit faire mon handler ?
Votre handler doit accepter une livraison dès qu'une signature fournie correspond à un secret de confiance.
Un récepteur qui ne vérifie que la première signature peut rejeter des livraisons valides après avoir changé de secret.
La spécification Standard Webhooks définit une liste de signatures afin que les récepteurs puissent essayer chacune d'elles pendant la rotation. Testez votre vérificateur avec plusieurs signatures avant d'effectuer la rotation d'un endpoint en production.
Maintenez les vérifications d'horodatage et de doublons tout au long du changement. La vérification de signature couvre ces contrôles.
Quelle est la séquence sûre ?
Enregistrez et déployez le nouveau secret. Confirmez la vérification avant la fin du chevauchement de l'ancien secret.
- Effectuez la rotation du secret de l'endpoint et stockez immédiatement la valeur renvoyée.
- Déployez la nouvelle valeur sur toutes les instances de récepteurs dans les 24 heures de chevauchement.
- Confirmez que les récepteurs vérifient les livraisons avec le nouveau secret, via les journaux des récepteurs et les tentatives de livraison de Bird.
- Laissez le secret précédent expirer automatiquement après le chevauchement.
Il n'y a pas d'étape de suppression distincte dans l'opération de rotation. Si l'ancien secret a été exposé, cessez de lui faire confiance dans vos récepteurs une fois qu'ils disposent du nouveau. La rotation seule laisse les récepteurs qui font confiance à l'ancien secret exposés pendant le chevauchement.
Que se passe-t-il si j'effectue une nouvelle rotation immédiatement ?
Une nouvelle rotation peut réussir tant que l'endpoint n'atteint pas cinq secrets valides simultanément.
En partant d'un seul secret, quatre rotations peuvent remplir ces cinq emplacements avant l'expiration des secrets plus anciens. La rotation suivante échoue avec WebhookTooManySecrets. Une boucle de rotation peut donc empêcher l'émission d'un nouveau secret au moment où vous en avez besoin.
Attendez qu'un secret plus ancien expire avant d'effectuer une nouvelle rotation. Les rotations répétées ne suppriment pas la nécessité de déployer le nouveau secret sur vos récepteurs.
Que se passe-t-il pour les livraisons qui ont échoué pendant le changement ?
Bird réessaye les livraisons échouées, donc corriger la vérification permet de les récupérer pendant la fenêtre de réessai.
La planification s'étend sur environ 27,5 heures avant les ajustements de temporisation. Une livraison échouée peut aussi être récupérée par rejeu après la fin des réessais ; réessais de webhooks échoués explique la fenêtre de rejeu.
Renvoyez une erreur pour une requête que vous ne pouvez pas vérifier. Renvoyer 2xx marque la livraison comme réussie, ce qui l'exclut du rejeu des événements manqués.
En bref
Déployez pendant la période de chevauchement.
Bird signe avec l'ancien et le nouveau secret pendant 24 heures, laissant aux récepteurs le temps d'adopter la nouvelle valeur.
Acceptez toute signature correspondante.
Un récepteur qui ne vérifie que la première signature peut rejeter une livraison valide pendant la rotation.
Enregistrez le nouveau secret immédiatement.
La réponse de rotation est le seul endroit où le nouveau secret est renvoyé.
La rotation est limitée à cinq secrets.
En partant d'un seul secret valide, quatre rotations remplissent les emplacements disponibles avant qu'un secret plus ancien n'expire.