Webhooks y Eventos
Un webhook es un servicio de notificación sistémica que permite la integración asíncrona entre sistemas — Unico IDCloud notifica a tu backend cada vez que un proceso cambia de estado, por lo que no necesitas hacer polling para recibir actualizaciones.
Esta sección cubre las cuatro cosas que necesitas para integrar webhooks: cómo configurar el endpoint y la autenticación, los eventos que Unico envía, la estrategia de fallback y los patrones de seguridad y confiabilidad que tu endpoint debe implementar.
Cuándo usar webhooks
Los webhooks son la forma recomendada de recibir notificaciones sobre la finalización de procesos. Son especialmente relevantes para:
- Human Token Journey (
humantoken,humantoken+revalidation) — para recibir una notificación cuando el usuario termina la jornada de un proceso creado con Crear Proceso. Los webhooks se disparan solo en el estado terminal (PROCESS_STATE_FINISHED); no se entregan eventos de progreso intermedios. - Flujos API Only (
api+humantoken,api+liveness+humantoken,api+liveness+humantoken+revalidation) — el resultado ya llega en la respuesta de Crear Proceso, por lo que estos flujos no dependen del webhook.
Los webhooks complementan, pero no reemplazan, los endpoints de GetProcess. Consulta Fallback.
En esta sección
- Configuración — registro de endpoints, métodos de autenticación (OAuth2, Basic, API Key), configuración de reintentos.
- Tipos de eventos — los eventos que Unico envía y la estructura del payload.
- Seguridad — idempotencia, límite de concurrencia y tasa de errores.
- Fallback — cómo recuperar el resultado del proceso cuando el webhook no está disponible.