Webhooks e Eventos

Um webhook é um serviço de notificação sistêmica que permite a integração assíncrona entre sistemas — o Unico IDCloud notifica o seu backend sempre que um processo muda de estado, eliminando a necessidade de polling para verificar atualizações.

Esta seção aborda as quatro coisas que você precisa para integrar webhooks: como configurar o endpoint e a autenticação, os eventos que a Unico envia, a estratégia de fallback e os padrões de segurança e confiabilidade que o seu endpoint deve implementar.

Quando usar webhooks

Webhooks são a forma recomendada de ser notificado sobre a conclusão de processos. Eles são particularmente relevantes para:

• Fluxos assíncronos de Web e SDK — para ser notificado quando um POST /client/v1/process termina de ser processado pelo lado da Unico.
• Fluxos de longa duração que combinam múltiplas capabilities (ex.: análise de documento + revisão manual). Os webhooks são disparados apenas no estado terminal (PROCESS_STATE_FINISHED); nenhum evento de progresso intermediário é entregue.

Webhooks complementam, mas não substituem, os endpoints GetProcess. Consulte Fallback.

Nesta seção

• Configuração — registro de endpoint, métodos de autenticação (OAuth2, Basic, API Key), configurações de retry.
• Tipos de evento — os eventos que a Unico envia e a estrutura do payload.
• Segurança — idempotência, limite de simultaneidade e taxa de erros.
• Fallback — como recuperar o resultado do processo quando o webhook não está disponível.