Cómo validar la firma de un webhook antes de procesarlo

Conserva los bytes necesarios para verificar

Revisa cómo entrega el cuerpo tu framework. Parsear JSON y volver a serializarlo puede cambiar espacios u orden y romper una firma calculada sobre el contenido original. Stripe exige el cuerpo sin modificar para su verificación; otros emisores tienen contratos distintos. Sigue el mecanismo documentado y, cuando exista, utiliza su biblioteca mantenida. No inventes una concatenación de campos ni compares firmas con un método casero sin revisar requisitos.

Identifica endpoint, entorno y secreto

Separa pruebas y producción y comprueba que el secreto pertenece al destino que recibe la petición. Guárdalo en el mecanismo de secretos previsto y limita su acceso. La clave de acceso a una API no tiene por qué ser el secreto de firma. Durante una rotación, aplica el periodo de coexistencia documentado por el proveedor y comprueba ambos extremos antes de retirar el valor antiguo; no desactives la validación para resolver una transición.

Comprueba antigüedad sin confundirla con duplicación

Si el esquema firmado incluye una marca temporal, aplica su comprobación de tolerancia según la documentación y mantén el reloj del servidor sincronizado. Una firma válida no demuestra que el evento sea nuevo ni que deba ejecutar cualquier acción. Después verifica cuenta, tipo de evento y reglas de negocio autorizadas. El control de duplicados pertenece a otra etapa y no sustituye la autenticidad de cada petición recibida.

Diagnostica sin abrir una excepción permanente

Si todas las firmas empiezan a fallar tras desplegar, compara configuración y manejo del cuerpo entre la versión anterior y la nueva. Comprueba si un proxy, middleware o parser está alterando la petición. Usa eventos de prueba autorizados y registra solo el detalle necesario para localizar la fase fallida. No copies el secreto a una captura o ticket compartido.

Prepara una prueba de integración que atraviese el mismo recorrido de red y aplicación que la entrega real. Un test aislado de la biblioteca puede pasar mientras el cuerpo llega modificado al servidor. Durante la reparación, conserva la política de rechazo y revisa cómo recuperará el emisor las entregas pendientes. La recuperación posterior debe volver a validar cada entrega y aplicar el control de repetición antes de ejecutar efectos.

Ensaya rechazos y recepción válida

Prueba un evento válido, un byte modificado, secreto incorrecto, cabecera ausente y una entrega fuera de la tolerancia definida. Ninguna prueba inválida debe alcanzar la ejecución de negocio. Registra motivo técnico y referencia sin revelar el secreto ni el cuerpo sensible en logs públicos. Tras verificar y aceptar de forma duradera el trabajo, organiza su procesamiento para responder dentro del plazo exigido. Si la persistencia falla, no finjas que lo has conservado: aplica la respuesta de error prevista por el emisor.

Fuentes y documentación

• Stripe: recepción de webhooks — Documenta firma sobre cuerpo original, duplicados y ausencia de garantía de orden.