Tus receptores pueden desplegarse en momentos distintos. Una superposición permite que un receptor con el secreto antiguo y otro con el nuevo autentiquen la misma entrega.
Sigue verificando las entregas durante todo el despliegue para que una solicitud de un atacante no pueda activar trabajo.
¿Qué sucede cuando roto el secreto?
Bird te da un nuevo secreto de firma. Despliégalo en un plazo de 24 horas, mientras Bird aún firma con el secreto anterior.
Llama a rotateWebhookSecret para tu endpoint. Guarda su secret, una cadena no vacía que comienza con whsec_, porque solo se devuelve en esa respuesta.
Bird firma cada entrega con ambos secretos durante la superposición. El encabezado webhook-signature contiene firmas separadas por espacios, cada una comenzando con v1,.
Un receptor puede verificar cualquiera de las firmas usando el secreto correspondiente. Completa el despliegue en un plazo de 24 horas porque el secreto antiguo deja de firmar después de esa ventana.
¿Qué tiene que hacer mi handler?
Tu handler debe aceptar una entrega cuando cualquier firma proporcionada coincida con un secreto en el que confía.
Un receptor que verifica solo la primera firma puede rechazar entregas válidas después de cambiar de secreto.
La especificación Standard Webhooks define una lista de firmas para que los receptores puedan probar cada una durante la rotación. Prueba tu verificador con múltiples firmas antes de rotar un endpoint en producción.
Mantén las comprobaciones de marca de tiempo y duplicados activas durante todo el cambio. Verificación de firma cubre esas comprobaciones.
¿Cuál es la secuencia segura?
Guarda y despliega el nuevo secreto. Confirma la verificación antes de que termine la superposición del secreto anterior.
- Rota el secreto del endpoint y almacena el valor devuelto de inmediato.
- Despliega el nuevo valor en todas las instancias de receptor dentro de la superposición de 24 horas.
- Confirma que los receptores verifican las entregas con el nuevo secreto, mediante los logs del receptor y los intentos de entrega de Bird.
- Deja que el secreto anterior expire automáticamente tras la superposición.
No hay un paso de eliminación separado en la operación de rotación. Si el secreto anterior quedó expuesto, deja de confiar en él en tus receptores después de que tengan el nuevo. Rotar por sí solo deja expuestos a los receptores que confían en el secreto anterior durante la superposición.
¿Qué pasa si roto de nuevo de inmediato?
Otra rotación puede tener éxito hasta que el endpoint alcance cinco secretos válidos simultáneamente.
Empezando con un secreto, cuatro rotaciones pueden llenar esos cinco espacios antes de que los secretos anteriores expiren. La siguiente rotación falla con WebhookTooManySecrets. Un bucle de rotación puede, por tanto, impedir que se emita otro secreto cuando lo necesitas.
Espera a que un secreto anterior expire antes de rotar de nuevo. Rotar repetidamente no elimina la necesidad de desplegar el nuevo secreto en tus receptores.
¿Qué pasa con las entregas que fallaron durante el cambio?
Bird reintenta las entregas fallidas, así que reparar la verificación puede recuperarlas durante la ventana de reintentos.
El calendario abarca aproximadamente 27,5 horas antes de ajustes de tiempo. Una entrega fallida también se puede recuperar mediante reproducción después de que terminen los reintentos; reintentos de webhook fallidos explica la ventana de reproducción.
Devuelve un error para una solicitud que no puedas verificar. Devolver 2xx marca la entrega como exitosa, lo que la excluye de la reproducción de eventos perdidos.
En resumen
Despliega durante la superposición.
Bird firma con el secreto antiguo y el nuevo durante 24 horas, dando tiempo a los receptores para adoptar el nuevo valor.
Acepta cualquier firma que coincida.
Un receptor que verifica solo la primera firma puede rechazar una entrega válida durante la rotación.
Guarda el nuevo secreto de inmediato.
La respuesta de rotación es el único lugar donde se devuelve el nuevo secreto.
La rotación tiene un límite de cinco secretos.
Empezando con un secreto válido, cuatro rotaciones llenan los espacios disponibles hasta que un secreto anterior expire.