Referencia de la API de Webhooks de FACEIO

Recibe notificaciones HTTPS POST cuando los usuarios se registran, se autentican con FACEIO o eliminan un Facial ID. Usa webhooks para mantener sincronizado tu backend con los eventos de autenticación facial sin depender únicamente del estado del frontend.

ABRIR FACEIO Console

Crea o selecciona una aplicación en FACEIO Console, registra un endpoint HTTPS y obtén el token de webhook asignado a la aplicación.

Descripción general de los Webhooks de FACEIO

Entrega de eventos en el servidor para registros, autenticaciones y eliminaciones de Facial ID

Los webhooks de FACEIO notifican a tu backend después de un nuevo registro, una autenticación correcta o una eliminación de Facial ID. Usa estos eventos del servidor para conciliar tus registros de cuenta con la actividad de FACEIO.

Cuando se activa un evento, FACEIO envía una solicitud HTTPS POST a la URL del endpoint de webhook configurada para tu aplicación. La carga JSON identifica el Facial ID único, el ID público de la aplicación, el nombre del evento, la dirección IP del cliente, la marca de tiempo, la carga vinculada cuando está disponible y detalles del registro, como la edad aproximada y el género.

Usa los eventos de webhook para actualizar registros del backend, crear un historial de auditoría o activar tu propio flujo del servidor. Valida cada webhook entrante antes de procesar su payload y sigue las buenas prácticas de seguridad de FACEIO.

Actualizaciones en tiempo real

Recibe notificaciones de eventos cuando los usuarios se registran, se autentican o completan la eliminación de un Facial ID.

Sincronización del backend

Actualiza los registros internos de las cuentas a partir de eventos confiables del servidor en lugar de depender únicamente de callbacks del navegador.

Configurar los Webhooks de FACEIO

Configura un endpoint de webhook para cada aplicación de FACEIO que necesite entregar eventos al backend. Tu endpoint debe aceptar JSON mediante HTTPS, validar el WWW-Authenticate token y devolver rápidamente una respuesta correcta.

Abrir FACEIO Console

Inicia sesión en tu cuenta en FACEIO Console ↗.

Abrir Application Manager

Desde la vista principal de la consola, abre Application Manager ↗.

Seleccionar la aplicación de destino

Elige la aplicación de FACEIO que debe enviar notificaciones de registro, autenticación y eliminación de Facial ID.

Abrir la pestaña Webhooks

Ve a la pestaña WEBHOOKS desde la vista de Application Manager.

Añadir la URL del endpoint

Introduce la URL del endpoint de webhook que recibirá los eventos de FACEIO y guarda la configuración de la aplicación.

✓

Empezar a recibir eventos

Después de activar un evento, FACEIO realizará una solicitud HTTPS POST a la URL del webhook con la carga JSON descrita a continuación.

Detalles de la solicitud HTTP

La URL de tu endpoint de webhook debe gestionar la solicitud HTTPS entrante iniciada por FACEIO cada vez que se activa un evento . El formato de la solicitud se resume a continuación.

Método HTTP	POST
Tipo de contenido	`application/json`
Carga POST	Objeto JSON. Consulta la sección siguiente para conocer los campos esperados del cuerpo.
Tiempo de espera	6 segundos Tu servidor HTTP debe aceptar la solicitud POST entrante en menos de 6 segundos. Después de ese tiempo, FACEIO cancela automáticamente la conexión.
Encabezado WWW-Authenticate El encabezado HTTP `WWW-Authenticate` siempre se incluye en cada solicitud POST iniciada por FACEIO.	Específico para cada aplicación de FACEIO *Verifica la autenticidad de la solicitud inspeccionando el valor del token Bearer* incluido en el encabezado HTTP `WWW-Authenticate`. Debe coincidir con la clave de token asignada a tu aplicación.** Obtén esta clave de token desde Application Manager en FACEIO Console ↗.

Buenas prácticas de seguridad

Verifica siempre las solicitudes de webhook entrantes comparando el token del encabezado WWW-Authenticate con la clave de token de tu aplicación. Rechaza las discrepancias, procesa los eventos de forma idempotente y revisa las buenas prácticas de seguridad antes de usar eventos de webhook en flujos de autorización en producción.

Cuerpo de la solicitud POST

El cuerpo de cada solicitud de webhook entrante de FACEIO es un objeto JSON. Usa los campos siguientes para identificar el evento, asociarlo con tu aplicación de FACEIO y conciliarlo con tus propios registros de cuenta.

webhook-payload.json

{
  "eventName": "String - Nombre del evento",
  "facialId": "String - Facial ID único del usuario objetivo",
  "appId": "String - ID público de la aplicación",
  "clientIp": "String - Dirección IP pública",
  "payload": "Blob - Datos vinculados al usuario, si existen (disponible desde el plan Business)",
  "details": {
    "timestamp": "String opcional - Marca de tiempo del evento",
    "gender": "String opcional - Género del usuario registrado",
    "age": "String opcional - Edad estimada del usuario registrado"
  }
}

Usa el valor del token del encabezado HTTP WWW-Authenticate, disponible en FACEIO Console ↗, para verificar la autenticidad de la solicitud.

`eventName`	es el nombre del evento que activó esta solicitud.
`facialId`	es el Facial ID único del usuario que está siendo registrado o autenticado
`appId`	es el ID público de la aplicación que activó esta solicitud. Puedes encontrar el ID público de cada aplicación en FACEIO Console ↗.
`clientIp`	es la dirección IP pública de la sesión del navegador que inicializó `fio.js`. Revisa las buenas prácticas de privacidad antes de almacenar o conservar datos de IP del cliente.
`payload`	son los datos que ya has asociado con este usuario, si los hay, durante el registro. Mantén los valores del payload al mínimo y evita almacenar secretos o datos personales innecesarios. Estos mismos datos también se reenviarán a tu frontend JavaScript en futuras autenticaciones del mismo usuario. El campo `payload` se incluye en la llamada de webhook solo si tu aplicación está en el Business Plan o superior. Consulta la página de precios para obtener más información. Este campo no se incluye en el evento de eliminación de Facial ID `DELETION`.

Campos opcionales (solo registro)

Los siguientes campos del cuerpo JSON se incluyen en los eventos de registro de nuevos usuarios:

`timestamp`	es la fecha de la operación (UTC) en formato YYYY-MM-DD.
`gender`	Género del usuario registrado: male o female.
`age`	Edad aproximada del usuario registrado.

Eventos

Cada solicitud HTTPS POST enviada a tu endpoint de webhook se activa mediante uno de los siguientes eventos de FACEIO. El campo eventName del cuerpo JSON contiene la clave correspondiente.

Nombre del evento	Descripción
`ENROLL`	Se activa después de que un usuario complete su registro.
`AUTH`	Se activa después de que un usuario complete su autenticación.
`DELETION`	Se activa después de la eliminación de Facial ID.

Consejos de implementación

Asegúrate de que tu endpoint de webhook responda en un máximo de 6 segundos para evitar tiempos de espera agotados.
Valida siempre el WWW-Authenticate token del encabezado por seguridad.
Gestiona los eventos de webhook de forma asíncrona e idempotente para evitar bloquear tu aplicación.
Registra únicamente los metadatos que necesites para depuración, conciliación y auditoría.
Devuelve un código de estado 200 OK para confirmar la recepción del webhook.
Usa la REST API cuando tu backend necesite verificar o conciliar el estado de Facial ID después de un evento.

Configura Webhooks para tu backend

Registra una URL de webhook HTTPS en FACEIO Console, valida el token del webhook en tu servidor y procesa los eventos de registro, autenticación y eliminación de Facial ID en tu backend.

Leer la guía de integración → Abrir FACEIO Console

URL de webhook HTTPS

Validación del token de webhook

Sincronización del backend basada en eventos