Seguridad al usar Webhooks

Seguridad por Diseño

Por defecto, los eventos de webhook se envían únicamente a la URL exacta que especificas en la creación de cada sesión. Para añadir una capa extra de seguridad y verificar el origen del evento, te recomendamos utilizar el objeto optionals.

¿Cómo funciona la validación con 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:

---