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:
- Flujos asíncronos de Web y SDK — para ser notificado cuando un
POST /client/v1/processtermina de procesarse en el lado de Unico. - Flujos de larga duración que combinan múltiples capacidades (p. ej., análisis de documentos + revisión manual). Los webhooks se activan únicamente en el estado terminal (
PROCESS_STATE_FINISHED); no se entregan eventos de progreso intermedios.
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.