Documentación de Auvral

Cada evento de webhook de Auvral, campo por campo, con cuerpos de ejemplo completos.

Todos los cuerpos de webhook tienen el mismo sobre. Entre eventos solo cambian type y el contenido de data.verification.

{
  "id": "string",
  "type": "string",
  "createdAt": "ISO 8601",
  "data": { "verification": { } }
}

Sobre

Campo	Tipo	Descripción
`id`	`string`	El id del evento. Coincide con el header `x-auvral-event-id` y es estable entre reintentos, así que esta es tu llave de deduplicación.
`type`	`string`	Uno de los tipos de evento de abajo.
`createdAt`	`string`	Cuándo ocurrió el evento, ISO 8601. No cuándo se hizo este intento de entrega.
`data.verification`	`object`	El estado de la verificación en ese momento.

`data.verification`

Campo	Tipo	Descripción
`id`	`string`	El id permanente de la verificación.
`status`	`"STARTED" \| "RUNNING" \| "VERIFIED" \| "REJECTED"`	El estado de la verificación cuando se generó el evento.
`flowId`	`string \| null`	El flujo que se corrió.
`flowName`	`string \| null`	El nombre visible del flujo.
`sessionId`	`string \| null`	La sesión de la que salió, el `sessionId` devuelto por `POST /v1/sessions`.
`referenceId`	`string \| null`	Tu propio identificador de la persona, tal como lo enviaste al crear la sesión, o el que Auvral asignó. Si lo editas en tu dashboard, cambia lo que llevan los eventos posteriores. Auvral nunca lo interpreta.
`metadata`	`object \| null`	Los pares clave-valor de strings planos que adjuntaste al crear la sesión, intactos, o `null` si no adjuntaste ninguno.
`startedAt`	`string \| null`	Cuándo empezó tu usuario, ISO 8601.
`endedAt`	`string \| null`	Cuándo se llegó al veredicto. `null` hasta entonces.
`steps`	`array`	Una entrada por paso del flujo, en el orden del flujo.

`steps[]`

Campo	Tipo	Descripción
`name`	`string`	El paso, en minúsculas: `document_verification`, `biometric_verification`.
`status`	`"PENDING" \| "RUNNING" \| "VERIFIED" \| "REJECTED"`	`PENDING` significa que el paso todavía no tiene resultado.

Cada paso configurado en el flujo aparece desde el primer evento, así que el largo del arreglo nunca cambia. Solo cambian los estados.

No hay ningún dato personal en ninguna parte del cuerpo: ni nombre, ni número de documento, ni fecha de nacimiento, ni imagen.

Los eventos de verificación

Tu usuario empezó la verificación. Se envía una vez, sin importar en qué dispositivo termine.

{
  "id": "1c8f2b90-3ad4-41e7-8f52-9b7c6d0e4a13",
  "type": "verification.started",
  "createdAt": "2026-08-25T15:11:02.884Z",
  "data": {
    "verification": {
      "id": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "STARTED",
      "flowId": "3f1c9a52-4d7e-4b3a-9c21-8e5f6a0b7d34",
      "flowName": "Onboarding",
      "sessionId": "9b2f4c1e-7a83-4d06-b5f1-2c9e8d3a6047",
      "referenceId": "user_8842",
      "metadata": { "orderId": "order-8841" },
      "startedAt": "2026-08-25T15:11:02.884Z",
      "endedAt": null,
      "steps": [
        { "name": "document_verification", "status": "PENDING" },
        { "name": "biometric_verification", "status": "PENDING" }
      ]
    }
  }
}

Útil para marcar a un usuario como "en proceso" y para detectar abandono: una verificación que empezó y nunca envió fue abandonada.

Lo envía únicamente Enviar evento de prueba en el dashboard. Todos los ids son el UUID de puros ceros, referenceId es la cadena literal test y metadata es null, así que no se puede confundir con uno real.

{
  "id": "b1e7d3f0-9c42-4a85-b6d1-8f03e5c7a294",
  "type": "webhook.test",
  "createdAt": "2026-08-25T14:02:00.000Z",
  "data": {
    "verification": {
      "id": "00000000-0000-0000-0000-000000000000",
      "status": "VERIFIED",
      "flowId": "00000000-0000-0000-0000-000000000000",
      "flowName": "Test flow",
      "sessionId": "00000000-0000-0000-0000-000000000000",
      "referenceId": "test",
      "metadata": null,
      "startedAt": "2026-08-25T14:02:00.000Z",
      "endedAt": "2026-08-25T14:02:00.000Z",
      "steps": [
        { "name": "document_verification", "status": "VERIFIED" },
        { "name": "biometric_verification", "status": "VERIFIED" }
      ]
    }
  }
}

Manéjalo explícitamente: verifica la firma como siempre, y luego devuelve 200 sin tocar el estado de tu negocio.

Orden

No se garantiza que los eventos lleguen en orden: un verification.submitted reintentado puede caer después de verification.succeeded. Guía tu lógica por type y data.verification.status, no por la secuencia de llegada. createdAt te da el orden real si lo necesitas.

Relacionado

Panorama de webhooks: entrega, reintentos, idempotencia.
Verificar firmas

Referencia de eventos