Seguridad al usar Webhooks

Verifica la firma de cada webhook

Todos los webhooks de Verificamex van firmados con tu clave en los headers webhook-id, webhook-timestamp y webhook-signature. Verificar esa firma es la forma recomendada de comprobar que el evento viene de Verificamex y no fue alterado. Consulta Verificar la firma de los webhooks para obtener tu clave y ver ejemplos de código.

Verificar la firma de los webhooks

Capa adicional: validación con optionals

Además de la firma, puedes asociar cada notificación con una sesión concreta enviando un token propio en optionals.

El campo optionals es un objeto comodín que puedes enviar en la petición de creación de sesión. Verificamex almacenará este objeto y lo incluirá exactamente igual en el payload de la notificación de webhook.

Esto te permite implementar un mecanismo de tokens de validación de un solo uso o firmas personalizadas:

1. Genera un Token Secreto: En tu servidor, genera un token único y aleatorio para cada sesión de verificación.
2. Envía el Token: Al crear la sesión de verificación, incluye el token dentro de un campo personalizado (por ejemplo, custom_webhook_secret) dentro del objeto optionals.
3. Guarda el Token: Registra ese token de forma temporal en tu base de datos asociado a la sesión de verificación.
4. Valida la Notificación: Cuando tu servidor reciba el webhook, comprueba que el custom_webhook_secret que viene dentro de optionals coincida con el que tienes almacenado.

---

Implementación Paso a Paso

1. Creación de la Sesión

Al enviar la solicitud para crear la sesión de verificación, define el objeto optionals. Puedes estructurarlo libremente según tus necesidades.

{
  "validations": "INE",
  "redirect_url": "https://tusitio.com/finalizado",
  "webhook": "https://tu-api.com/v1/webhooks/verificamex",
  "optionals": {
    "client_id": "cli_92813",
    "custom_webhook_secret": "vfx_sec_89dfh23jkd9812s"
  }
}

A continuación se muestra cómo se visualiza esta estructura en la solicitud:

2. Recepción del Webhook

Cuando el proceso finaliza, el evento que enviamos a tu servidor incluirá la misma estructura que definiste en la petición dentro del bloque optionals.

{
  "data": {
    "object": "VerificationSession",
    "id": "9d805854-f8a1-4135-ad57-3629ca0fc679",
    "status": "CLOSED",
    "result": "SUCCESS",
    "optionals": {
      "client_id": "cli_92813",
      "custom_webhook_secret": "vfx_sec_89dfh23jkd9812s"
    },
    ...
  }
}

Así es como se visualiza el payload recibido:

---