Uso de Webhooks en Verificamex

Configurar webhooks te permite automatizar procesos en tu backend al recibir notificaciones instantáneas sobre cambios de estado en tus verificaciones, eliminando la necesidad de realizar consultas constantes a nuestra API (Polling).

Configuración del Webhook

Para empezar a recibir eventos, debes proporcionar una URL válida al momento de iniciar una sesión de verificación.

Define tu Endpoint: Prepara una URL en tu servidor (ej. https://tu-api.com/webhooks/callback) que acepte solicitudes POST con cuerpo JSON.
Parámetro webhook: Al consumir el endpoint de Crear Sesión de Verificación, incluye la URL en el cuerpo de la petición.
Parámetro with_webhook_binaries (Opcional): Establece este valor en true si deseas que el payload incluya las imágenes (Selfie e INE) codificadas en Base64.

Ejemplo de Solicitud

A continuación se muestra cómo registrar un webhook al crear una sesión:

JSON
cURL

{
  "validations": "INE",
  "redirect_url": "https://tusitio.com/finalizado",
  "webhook": "https://tu-api.com/v1/webhooks/verificamex",
  "with_webhook_binaries": false
}

curl -X POST https://api.verificamex.com/identity/v2/identity/sessions \
  -H "Authorization: Bearer {TU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "validations": "INE",
    "webhook": "https://tu-api.com/v1/webhooks/verificamex",
    "with_webhook_binaries": true
  }'

Estructura del Payload (Notificación)

Cuando una sesión de verificación cambia su estado a CLOSED, Verificamex enviará un POST a tu URL con el resultado final:

{
    "data": {
        "object": "VerificationSession",
        "id": "9d805854-f8a1-4135-ad57-3629ca0fc679",
        "status": "CLOSED",
        "result": "SUCCESS",
        "validations": ["INE", "CURP"],
        "ine": {
            "status": true,
            "data": { ... }
        },
        "renapo": {
            "status": true,
            "data": { ... }
        },
        "created_at": "2024-11-16T08:27:13.000000Z"
    }
}

Mejores Prácticas y Seguridad

Respuesta 200 OK

Tu servidor debe responder con un código HTTP 200 para confirmar la recepción exitosa.

Idempotencia

Diseña tu lógica para manejar posibles reintentos de un mismo evento sin duplicar acciones en tu base de datos.

Procesamiento Async

Si el procesamiento de los datos es pesado, te recomendamos usar una cola de mensajes (Redis, RabbitMQ) y responder rápido al webhook.

HTTPS Requerido

Por seguridad, solo enviamos notificaciones a URLs que utilicen el protocolo cifrado HTTPS.