Como autenticar a Shinkansen cuando se invocan tus Webhooks

Firma digital 🔏

Los requests generados desde Shinkansen incluyen la cabecera HTTP Shinkansen-JWS-Signature que te permite autenticar su origen (Shinkansen) y además garantiza la integridad del mensaje.

Siempre debes validar estas firmas como te lo explicamos en esta página de la documentación.

Certificados 📜

Para las llaves públicas que permiten validar esas firmas, en Shinkansen se registran certificados. Los certificados activos los encuentras en nuestro dashboard (Configuración → Certificados) y se renuevan en general cada 2 años.

Cuando va a expirar un certificado, ponemos en producción uno nuevo al menos 2 semanas antes de la expiración del anterior. Lo que también aparecerá en el dashboard de Shinkansen.

En casos excepcionales, los clientes tienen la opción de continuar utilizando la firma del certificado antiguo por un tiempo después de que se emita el nuevo certificado, hasta que puedan configurar sus sistemas para usar el nuevo.

El certificado actual es válido desde el 11-09-2023 hasta el 10-09-2025.

¿Direcciones IP de Origen? 🙅🏻‍♂️

Las notificaciones de webhooks de Shinkansen no provienen de un conjunto fijo de direcciones IP o rangos de IP.

Aunque recibas la mayoría (o todas) nuestras notificaciones desde una única dirección IP, no te lo garantizamos a futuro debido a las necesidades de escalabilidad.

La firma digital en cada transacción es el mecanismo que garantiza la integridad y no repudio del mensaje, en lugar de depender de una dirección IP de origen fija.

¿Otras autenticaciones en el Request? (API Key, secrets)

Actualmente, Shinkansen no admite el envío de una API Key en los encabezados de las notificaciones de webhook.

Sin embargo, puedes agregar una cadena secreta aleatoria en la URL del webhook o como un parámetro de consulta, en caso que tus sistemas requieren un mecanismo de autenticación adicional.