Webhooks (V3)

Si al crear la sesión incluiste el parámetro webhook, te enviaremos una petición POST con cuerpo JSON cada vez que la sesión cambie de estado.

Esto te evita consultar la API de forma periódica para saber si la verificación terminó.

Eventos que recibirás

1. VERIFYING — El usuario terminó de capturar sus documentos. Recibirás varias notificaciones con este estado conforme avanzan las validaciones contra Lista Nominal y RENAPO.
2. FINISHED — El proceso concluyó. El campo result trae el puntaje de la verificación.

Si el proceso no puede completarse, recibirás una notificación con estado FAILED y result en 0.

Nota

La creación de la sesión no genera notificación: el POST de creación ya te devolvió esos datos de forma síncrona.

Estructura del payload

El cuerpo es el mismo que devuelve el endpoint de detalle, envuelto en data y meta, con las relaciones ine, renapo y files ya incluidas.

{
    "data": {
        "object": "VerificationSession",
        "id": "870c7eee-3604-4995-aa98-bc8fa6aa1112",
        "status": "FINISHED",
        "result": 100,
        "errors": null,
        "comments": null,
        "only_mobile_devices": true,
        "redirect_url": "https://tusitio.com/finalizado",
        "webhook": "https://tu-api.com/webhooks/verificamex",
        "validations": ["INE", "CURP"],
        "document_data": {
            "cic": "123456789012",
            "curp": "PEPJ820131HDFRRN09",
            "id_ciudadano": "012345678"
        },
        "ocr": {
            "ocr_frontal": {
                "num_emisiones": "00",
                "anio_registro": "2022",
                "clave_elector": "PEPJ820131H400",
                "curp": "PEPJ820131HDFRRN09",
                "domicilio": "CALLE FALSA 123\nCOL CENTRO\nCDMX",
                "address": {
                    "ln1": "CALLE FALSA 123",
                    "ln2": "COL CENTRO",
                    "ln3": "CDMX"
                },
                "demarcacion": "CDMX",
                "fecha_nacimiento": "31/01/1982",
                "nombre_completo": "PEREZ\nJUAREZ\nPEPE",
                "primer_apellido": "PEREZ",
                "seccion": "1234",
                "segundo_apellido": "JUAREZ",
                "sexo": "H",
                "vigencia": "2030",
                "codigo_postal": "06000",
                "nombres": "PEPE",
                "anio_emision": "2022",
                "version_frontal": "GH"
            },
            "ocr_reverso": {
                "mrz": "IDMEXPEPJ820131<<<<<<<<<<<<<<<\n8201314H3001019MEX<<<<<<<<<<<0\nPEREZ<<JUAREZ<<PEPE<<<<<<<<<<<"
            }
        },
        "verifications": {
            "fecha_nacimiento_match": true,
            "sexo_match": true,
            "seccion_match": true
        },
        "coincidence": 95.5,
        "optionals": { "id_cliente": "A-10293" },
        "form_url": "https://app.verificamex.com/verification/870c7eee-3604-4995-aa98-bc8fa6aa1112",
        "created_at": "2026-07-21T22:40:55.000000Z",
        "updated_at": "2026-07-21T22:48:03.000000Z",
        "readable_created_at": "hace 8 minutos",
        "readable_updated_at": "hace 1 minuto",
        "files": [
            {
                "object": "VerificationFiles",
                "id": "9d8058ab",
                "file_type": "ID_FRONT",
                "mime_type": "image/jpeg",
                "size": 284736,
                "url": "https://storage.googleapis.com/...&X-Goog-Signature=...",
                "created_at": "2026-07-21T22:47:00.000000Z",
                "updated_at": "2026-07-21T22:47:00.000000Z"
            }
        ]
    },
    "meta": {
        "include": "ine,renapo,files"
    }
}

Diferencia con la V2

En la V2 estos mismos datos se entregan como data.ine_reading.DocumentData, un arreglo de objetos {Type, Source, Value}. La V3 los aplana en document_data, ocr, verifications y coincidence — ver el detalle de estos campos en el endpoint de detalle.

Controlar el peso de la notificación

Diferencia con la V2

El webhook de V3 nunca incluye el contenido de los archivos en Base64 — a diferencia de la V2, aquí no existe un binary que activar o desactivar. Cada archivo viaja únicamente como URL firmada, vigente 20 minutos (más que los 15 del endpoint de detalle, para dar margen a que tu servidor la procese).

Si no necesitas los archivos en la notificación, envía with_webhook_files: false al crear la sesión: la llave files se omite por completo del payload y podrás obtener los archivos cuando los requieras desde el detalle de la sesión.

Tu endpoint debe responder 200

Consideramos entregada la notificación únicamente si tu servidor responde con el código HTTP 200. Cualquier otro código, incluidos 201 o 204, se toma como fallo y la notificación se reintenta hasta 3 veces, una por minuto.

Buenas prácticas

Responde rápido

Si el procesamiento es pesado, encola el trabajo y responde 200 de inmediato.

Idempotencia

Recibirás varias notificaciones por sesión y puede haber reintentos. Usa el id de la sesión y el status para no duplicar acciones.

Usa HTTPS

Expón tu endpoint sobre HTTPS para que el contenido de la notificación viaje cifrado.

Valida el origen

Las notificaciones no van firmadas. Usa optionals para incluir un token propio que puedas verificar al recibir el evento.

Consejo

Puedes usar webhook.site para inspeccionar la estructura de los eventos antes de escribir tu integración.