Webhooks
Webhooks entregam eventos relevantes da plataforma ao seu backend para sincronizar estado, destravar fluxos e registrar auditoria.
#Quando usar webhooks
Use webhooks quando seu backend precisa reagir sem manter uma conexão SSE aberta:
- atualizar status de uma conversa;
- registrar que uma resposta foi produzida;
- acionar notificações internas;
- consolidar métricas próprias;
- iniciar uma próxima etapa em outro sistema.
Para uma interface em tempo real, use stream de session. Para integração backend-to-backend, use webhooks.
#Eventos entregáveis
Webhooks são inscritos em eventos de alto valor operacional, como mensagens do agent e mudanças de status da session. Eventos internos de baixo nível ficam fora da entrega por padrão para manter payloads estáveis e úteis.
#Assinatura e rotação
Cada webhook tem um secret usado para assinar entregas. Ao rotacionar, você pode manter uma janela de graça para validar o secret antigo e o novo durante o deploy do consumidor.
Armazene o secret no seu backend e valide a assinatura antes de processar o payload.