​
Webhooks

Use webhooks para que a idCerberus avise a sua aplicação quando um onboarding mudar de status, ou quando uma consulta avulsa terminar de processar, em vez de sua aplicação precisar ficar perguntando (polling).

​
O que é, por que existe, pra que serve

  1. O que é: uma URL da sua aplicação que a idCerberus chama automaticamente (POST) toda vez que o processamento de um onboarding muda de status.
  2. Por que existe: consultar GET /api/onboarding/report/{tokenOnboarding} em loop até o status sair de IN_PROCESS funciona, mas gasta chamadas e atrasa a reação da sua aplicação. O webhook inverte isso: você é avisado no momento em que há novidade.
  3. Pra que serve pra você: é a forma recomendada de acompanhar onboarding em produção. Reserve o polling (veja Onboarding via SDK) para quando o webhook ainda não estiver configurado, ou como conferência ocasional.
Configurar o webhook (URL e chave de segurança) hoje é feito pelo time da React IT, não é self-service pela API. Peça a ativação em [email protected] informando a URL que deve receber as chamadas.

​
Como funciona

  1. Algo relevante acontece: um onboarding muda de status (sai de IN_PROCESS para APPROVED ou REFUSED), uma decisão de revisão manual é tomada, ou uma consulta avulsa em POST /api/service-api termina de processar.
  2. A idCerberus monta o conteúdo (o mesmo formato de GET /api/onboarding/report/{tokenOnboarding}, adaptado quando a origem é uma consulta avulsa).
  3. A idCerberus faz POST desse conteúdo para a URL configurada no seu produto.
  4. Sua aplicação responde com sucesso (2xx) para confirmar o recebimento.
O webhook não é instantâneo no sentido estrito. Processamento automático de onboarding é verificado a cada poucos segundos e disparado quando encontra uma mudança; consulta avulsa dispara o webhook cerca de 10 segundos depois da resposta HTTP. Decisão de revisão manual (alguém aprova/recusa pelo backoffice) dispara na hora. Nenhum desses tempos é um SLA contratual. Trate como comportamento observado, não como garantia.
Se a sua aplicação não responder com sucesso, a chamada é marcada internamente como pendente de nova tentativa, mas não existe um processo automático que fica reenviando entregas que falharam. Um novo envio só acontece se: (a) o mesmo onboarding mudar de conteúdo de novo mais tarde (dispara como entrega nova, não como retry), ou (b) alguém com acesso ao Backoffice forçar o reenvio manualmente na tela. Por isso, não trate webhook como garantia de entrega. Mantenha o polling (GET /api/onboarding/report/{tokenOnboarding}) como rede de segurança real, não só como formalidade.

​
Payload

O formato do corpo depende da origem do evento. Onboarding (SDK ou Cliente Web): mesmo formato do relatório de onboarding.
Veja a tabela de campos completa em Onboarding via SDK: é a mesma estrutura. Consulta avulsa (POST /api/service-api): o mesmo JSON que já veio na resposta HTTP síncrona da chamada (result, status, onboardingStatus e externalId), não o formato de relatório de onboarding acima.

​
Autenticar a chamada recebida

Toda chamada de webhook chega com um header de verificação:
Antes de processar o payload, confira se id-cerberus-token bate com a chave que a React IT te passou ao configurar o webhook. Isso confirma que a chamada veio mesmo da idCerberus, e não de terceiros que descobriram sua URL.
Não exponha a webhookKey no front-end nem em repositórios públicos. Trate-a como qualquer outro segredo de autenticação.

​
Boas práticas

  1. Responda rápido (idealmente abaixo de alguns segundos) e processe o conteúdo depois, de forma assíncrona. Um endpoint lento pode ser interpretado como falha.
  2. Sempre valide o header id-cerberus-token antes de confiar no payload.
  3. Trate eventos repetidos. Reprocessar o mesmo tokenOnboarding com o mesmo status não deve causar efeito colateral duplicado.
  4. Não trate REFUSED como erro técnico. É um resultado de negócio, igual ao consumo avulso via polling. Veja Status e erros.
  5. Mantenha um fallback de polling. Como não existe reenvio automático para entregas que falharam (veja “Como funciona” acima), esse fallback é o que garante que sua aplicação não fique presa esperando um evento que não vai chegar sozinho.

​
Dúvidas comuns

Não. Use o webhook como principal e o polling (GET /api/onboarding/report/{tokenOnboarding}) como conferência ou fallback, especialmente logo após configurar o webhook pela primeira vez.
Sim, se o seu produto tiver webhook configurado. Consultas avulsas em POST /api/service-api já retornam o resultado direto na resposta HTTP; o webhook chega depois (por volta de 10 segundos), com o mesmo conteúdo. Na prática ele é redundante para consumo avulso simples; ele importa mais quando você quer centralizar tudo (avulso e onboarding) num único listener em vez de tratar a resposta síncrona da API em vários lugares do seu código.
A configuração é uma URL por produto. Se você precisa distribuir eventos para múltiplos sistemas internos, receba na sua própria URL e distribua a partir dali.
Faça um onboarding de teste em homologação e confirme se a sua URL recebeu a chamada. Se não tiver certeza se a configuração foi aplicada, confirme com quem liberou o acesso.

​
Próximo passo

Onboarding via SDK

Veja o fluxo completo que gera os eventos que o webhook avisa.

Backoffice

Veja logs de tentativas e force um reenvio manual pela tela.

Status e erros

Entenda como interpretar REFUSED, ERROR e os demais status recebidos.

Glossário

Confira termos como id-cerberus-token e tokenOnboarding.