Webhooks de sesiones de pasaporte

Si enviaste el parámetro webhook al crear la sesión de pasaporte, Verificamex te enviará una petición POST a esa URL cada vez que cambie el status de la sesión, con el mismo objeto que devuelve Consultar resultado de una sesión de pasaporte.

El mecanismo es el mismo que el de las sesiones V2 de INE; revisa Introducción a los Webhooks y Verificar la firma de los webhooks para saber cómo recibirlos y validarlos.

Eventos que recibirás

status	Cuándo se envía
VERIFYING	El usuario terminó la captura y empezó el análisis del pasaporte. Todavía no trae passport.
FINISHED	La verificación terminó. Revisa result: 100 aprobada, 0 si no se pudieron cobrar los tokens.
FAILED	El documento no es un pasaporte o no pasó las verificaciones. El motivo viene en errors.

Nota

No se envía un evento al crear la sesión: la respuesta del endpoint de creación ya te da el id y el form_url. Si el análisis todavía no está listo, la sesión puede regresar momentáneamente a OPEN y recibirás ese evento antes de un nuevo VERIFYING. Considera definitivo solo FINISHED o FAILED.

Diferencias con el webhook de INE

• meta.include vale "passport,files" en lugar de "ine,renapo,files".
• Trae el objeto passport con la lectura del pasaporte; no trae ine ni renapo.
• validations siempre es un arreglo vacío.

Usa meta.include para distinguir en tu receptor si el evento es de una sesión de pasaporte o de INE.

Archivos en el webhook

Si with_webhook_binaries es true (valor por defecto), el webhook incluye files.data con cada evidencia en Base64 en el campo binary y una URL firmada en url. Puedes acceder a ellos como data.files.data[0].binary.

Si creaste la sesión con with_webhook_binaries: false, el webhook no incluye files: descárgalos después con Consultar resultado de una sesión de pasaporte.

Precaución

Con binarios, cada petición puede pesar varios MB (incluye el video de la prueba de vida). Asegúrate de que tu servidor acepte cuerpos de ese tamaño.

Ejemplos

FINISHED (result: 100)

{
    "data": {
        "object": "VerificationSession",
        "id": "9d805854-f8a1-4135-ad57-3629ca0fc679",
        "status": "FINISHED",
        "result": 100,
        "errors": null,
        "comments": null,
        "only_mobile_devices": false,
        "redirect_url": "https://www.tusitio.com/gracias",
        "webhook": "https://www.tusitio.com/webhooks/verificamex",
        "validations": [],
        "ine_reading": {
            "DocumentData": [
                { "Type": "DocumentNumber", "Name": "Número de documento", "Value": "G00000001", "Source": "MRZ" }
            ],
            "DocumentVerifications": [
                { "Category": "Biometrics", "Key": "Biometrics_FaceMatching", "Name": "Comprobación Facial", "Result": "Ok", "Output": "99.97" }
            ]
        },
        "optionals": {
            "folio": "CLI-1001"
        },
        "form_url": "https://app.verificamex.com/verification/9d805854-f8a1-4135-ad57-3629ca0fc679",
        "created_at": "2026-10-03T08:27:13.000000Z",
        "updated_at": "2026-10-03T08:31:02.000000Z",
        "readable_created_at": "hace 4 minutos",
        "readable_updated_at": "hace 1 segundo",
        "passport": {
            "data": {
                "object": "PassportReading",
                "id": "NxOpZowo9GmjKqdR",
                "verified": true,
                "document_type": "Passport",
                "country_code": "MEX",
                "document_number": "G00000001",
                "name": "MARÍA FERNANDA",
                "surname": "LÓPEZ GARCÍA",
                "father_surname": "LÓPEZ",
                "mother_surname": "GARCÍA",
                "sex": "F",
                "nationality": "MEX",
                "issuing_state": "MEX",
                "personal_number": "LOGM900903MDFPRR09",
                "date_of_birth": "1990-09-03",
                "date_of_issue": "2025-04-15",
                "date_of_expiry": "2035-04-15",
                "place_of_birth": "CIUDAD DE MÉXICO",
                "issuing_authority": "OF. PASAPORTES CDMX",
                "global_result": "Ok",
                "security_level": "Medium",
                "total_checks": 29,
                "success_checks": 29,
                "warning_checks": 0,
                "failed_checks": 0,
                "face_matching_confidence": 99.97,
                "liveness_passed": true,
                "created_at": "2026-10-03T08:30:58.000000Z",
                "updated_at": "2026-10-03T08:30:58.000000Z"
            }
        },
        "files": {
            "data": [
                {
                    "object": "VerificationFiles",
                    "id": "a1d41e5c-d533-4b7a-995c-5269941a35a7",
                    "file_type": "PDF_VERIFICATION_REPORT",
                    "mime_type": "application/pdf",
                    "size": 232761,
                    "url": "https://storage.googleapis.com/...&X-Goog-Signature=...",
                    "created_at": "2026-10-03T08:30:57.000000Z",
                    "updated_at": "2026-10-03T08:30:57.000000Z",
                    "binary": "JVBERi0xLjQNCiW0tba3DQol..."
                },
                {
                    "object": "VerificationFiles",
                    "id": "a1d41e60-888b-4168-8951-bc915828c877",
                    "file_type": "PASSPORT_FRONT",
                    "mime_type": "image/png",
                    "size": 331008,
                    "url": "https://storage.googleapis.com/...&X-Goog-Signature=...",
                    "created_at": "2026-10-03T08:30:59.000000Z",
                    "updated_at": "2026-10-03T08:30:59.000000Z",
                    "binary": "iVBORw0KGgoAAAANSUhEUgAA..."
                }
            ]
        }
    },
    "meta": {
        "include": "passport,files"
    }
}

FAILED (result: 0)

{
    "data": {
        "object": "VerificationSession",
        "id": "b3f1c2d4-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
        "status": "FAILED",
        "result": 0,
        "errors": [
            {
                "Key": "DOC-PASSPORT-002",
                "Name": "Tipo de documento",
                "Category": "PassportValidation",
                "Result": false,
                "Output": "IdCard",
                "Message": "El documento capturado no es un pasaporte"
            }
        ],
        "validations": [],
        "optionals": {
            "folio": "CLI-1002"
        },
        "passport": {
            "data": {
                "object": "PassportReading",
                "verified": true,
                "document_type": "IdCard",
                "global_result": "Ok"
            }
        }
    },
    "meta": {
        "include": "passport,files"
    }
}

Ejemplo resumido de una sesión en la que el usuario capturó una credencial en lugar de un pasaporte. Aunque esa credencial se haya leído bien, la sesión se rechaza porque no es un pasaporte.

Consejo

Te recomendamos usar https://webhook.site para probar y visualizar los eventos del webhook y su estructura.