Eventos Webhook

Los eventos enviados mediante webhook se generan en distintas etapas del proceso. Cada evento incluye los datos correspondientes según el estado alcanzado.

INFORMACIÓN

Para recibir webhooks, se debe proporcionar la URL en el campo callbackUrl, donde se enviarán los eventos mediante HTTP POST. Este campo se especifica al momento de registrar la solicitud de firma.

Flujo de Validación

El proceso de firma tradicional contempla las siguientes etapas:

Registro Civil

Se valida la información del solicitante contra el Registro Civil.

Inicio de Sesión

El solicitante inicia la sesión de firma con sus credenciales.

Prueba de Vida (Liveness)

El solicitante realiza una prueba de vida para la verificación biométrica de identidad.

Contraseña y Confirmación de Datos

El solicitante define su contraseña y confirma que sus datos están correctos previo a la generación del certificado de firma electrónica.

Emisión del Certificado

Se genera el certificado de firma electrónica y se le da la opción al solicitante de descargarlo.

Contrato y Envío

Se genera el contrato y se envía al solicitante el certificado y el contrato a través de su correo electrónico. Este proceso se realiza de manera asincrónica luego de generarse el certificado de firma electrónica.

Formato del Payload

Todos los eventos se envían como un envelope CloudEvents 1.0 en formato structured/JSON. El cuerpo del HTTP POST siempre tiene esta estructura:

Atributo	Descripción
`specversion`	Versión de la especificación CloudEvents. Siempre `"1.0"`.
`id`	Identificador único del evento (UUID). Úselo para idempotencia del lado del consumidor.
`source`	Origen del evento. `"/firmasegura/signature-service"`.
`type`	Tipo de evento en notación reverse-DNS (ver cada evento más abajo).
`subject`	Identificador de la sesión de firma (`sessionId`).
`time`	Marca de tiempo de emisión (ISO 8601 con zona horaria).
`datacontenttype`	Tipo de contenido de `data`. `"application/json"`.
`data`	Detalle del evento. Solo presente en eventos con detalle (`SESSION_REJECTED` / `SESSION_ERROR`); se omite en el resto.

NOTA

El nombre lógico del evento (SESSION_COMPLETED, SESSION_REJECTED, etc.) viaja en el atributo type con su valor reverse-DNS. El sessionId viaja en subject. Cuando el evento tiene detalle, el code y el message viajan dentro de data, no en el nivel superior.

Eventos

A continuación, se describen los eventos enviados por webhook durante el proceso.

SESSION_COMPLETED

Se emite cuando el proceso de firma tradicional ha concluido exitosamente en todas sus etapas.

type: ec.firmasegura.signature.session.completed

{
  "specversion": "1.0",
  "id": "a1b2c3d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "source": "/firmasegura/signature-service",
  "type": "ec.firmasegura.signature.session.completed",
  "subject": "b3f1a2d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "time": "2026-07-24T10:15:30-05:00",
  "datacontenttype": "application/json"
}

SESSION_REJECTED

Se emite cuando la sesión es rechazada de forma definitiva por una regla de negocio. No es posible continuar el proceso; se debe generar una nueva solicitud.

type: ec.firmasegura.signature.session.rejected

{
  "specversion": "1.0",
  "id": "a1b2c3d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "source": "/firmasegura/signature-service",
  "type": "ec.firmasegura.signature.session.rejected",
  "subject": "b3f1a2d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "time": "2026-07-24T10:15:30-05:00",
  "datacontenttype": "application/json",
  "data": {
    "code": "FACE_LIVENESS_EXHAUSTED",
    "message": "Se agotaron todos los intentos de verificación facial, la solicitud ha sido rechazada, por favor genera una nueva"
  }
}

Los posibles valores de data.code para este evento son:

code	Descripción
FACE_LIVENESS_EXHAUSTED	Se agotaron todos los intentos de verificación biométrica
DATA_REJECTED_BY_USER	El titular rechazó sus datos personales
OTP_TOTAL_LIMIT_EXCEEDED	Se superó el límite máximo de intentos de verificación de correo

SESSION_ERROR

Se emite cuando ocurre un error técnico en una etapa del proceso. La sesión queda en estado de error; dependiendo del caso puede reintentarse la tarea fallida.

type: ec.firmasegura.signature.session.error

{
  "specversion": "1.0",
  "id": "a1b2c3d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "source": "/firmasegura/signature-service",
  "type": "ec.firmasegura.signature.session.error",
  "subject": "b3f1a2d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "time": "2026-07-24T10:15:30-05:00",
  "datacontenttype": "application/json",
  "data": {
    "code": "CERTIFICATE_GENERATION_FAILED",
    "message": "No pudimos generar tu certificado digital, por favor intenta de nuevo"
  }
}

Los posibles valores de data.code para este evento son:

code	Descripción
PASSWORD_ENCRYPTION_FAILED	Error al procesar la contraseña del solicitante
CERTIFICATE_GENERATION_FAILED	Error al generar el certificado de firma electrónica
CONTRACT_GENERATION_FAILED	Error al generar la documentación del contrato
SEND_FAILED	Error al enviar los documentos al solicitante

SESSION_CANCELLED

Se emite cuando la solicitud es anulada/cancelada a través del endpoint de cancelación. El enlace de la sesión deja de estar disponible.

type: ec.firmasegura.signature.session.cancelled

{
  "specversion": "1.0",
  "id": "a1b2c3d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "source": "/firmasegura/signature-service",
  "type": "ec.firmasegura.signature.session.cancelled",
  "subject": "b3f1a2d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "time": "2026-07-24T10:15:30-05:00",
  "datacontenttype": "application/json"
}

SESSION_EXPIRED

Se emite cuando una sesión con el enlace vencido es expirada. Ocurre de dos formas: al intentar operar sobre una sesión cuyo enlace ya venció, o de forma proactiva mediante el proceso programado que expira las sesiones vencidas (con un periodo de gracia de 1 hora luego del vencimiento del enlace).

type: ec.firmasegura.signature.session.expired

{
  "specversion": "1.0",
  "id": "a1b2c3d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "source": "/firmasegura/signature-service",
  "type": "ec.firmasegura.signature.session.expired",
  "subject": "b3f1a2d4-7c8e-4f0a-9b2d-1e3c5f7a9b0d",
  "time": "2026-07-24T10:15:30-05:00",
  "datacontenttype": "application/json"
}

NOTA

Los errores corregibles por el usuario (código OTP incorrecto, contraseña débil, obstrucción en selfie, etc.) no generan webhook. Solo se notifican los eventos que representan un cambio de estado definitivo de la sesión.

Flujo de Validación#

Formato del Payload#

Eventos#

SESSION_COMPLETED#

SESSION_REJECTED#

SESSION_ERROR#

SESSION_CANCELLED#

SESSION_EXPIRED#

Flujo de Validación

Formato del Payload

Eventos

SESSION_COMPLETED

SESSION_REJECTED

SESSION_ERROR

SESSION_CANCELLED

SESSION_EXPIRED