1. Eventos de Ciclo de Vida da Sessão (Session Lifecycle)
Os eventos de sessão permitem rastrear o estado de uma conversa desde a sua abertura até o encerramento ou transição.
session.opened: Acionado no momento exato em que uma nova sessão é iniciada.session.closed: Acionado quando uma sessão termina (geralmente devido à inatividade).session.closed.unforwarded: Acionado quando uma sessão é encerrada sem ter sido transferida para um agente humano ou fluxo externo.session.analyzed: Acionado após o processamento de IA, quando os campos inteligentes (smart fields) são calculados e o resumo da conversa é gerado.session.stage.transitioned: Acionado quando uma sessão se move entre diferentes etapas do pipeline (ex: de Prospecto para Qualificado).session.*: Caractere curinga (Wildcard). Subscreve-se a todos os eventos de ciclo de vida e de transferência simultaneamente.
Eventos de Transferência (Session Transfer)
session.forwarded: Evento genérico acionado quando uma sessão é transferida por qualquer motivo.session.forwarded.qualified: A sessão foi transferida por atender aos critérios de qualificação.session.forwarded.escalated: A sessão foi transferida através de um caminho de escalonamento (ex: bot para supervisor).session.forwarded.recovered: A sessão foi transferida como parte de um fluxo de recuperação.
2. Eventos de Execução de Função (Function Execution)
Esses eventos monitoram quando o motor de IA executa ferramentas ou funções externas.
function.call.<functionName>: Acionado quando uma função específica é executada.function.call.*: Subscreve-se a todas as chamadas de função.function.*: Subscreve-se a todos os eventos relacionados a funções.
3. Estrutura do Payload do Webhook
Todos os webhooks do Darwin possuem uma estrutura padronizada para garantir a consistência:
Propriedades Comuns
Propriedade | Descrição |
| O tipo de evento (ex: |
| O registro de data/hora de quando o evento ocorreu. |
| O ID do agente relacionado ao evento. |
| O nome do agente relacionado ao evento. |
| Dados adicionais específicos do evento. |
Detalhes do Objeto data
Para Sessões: Inclui
sessionId,channelName,summary,smartFieldse registros de atividade comolastHumanActivityAt.Para Funções: Inclui
inputs(parâmetros enviados),functionStatus,functionCallIde metadados da aplicação.
4. Segurança e Integridade do Payload
Para garantir que os webhooks originem-se do Darwin e não tenham sido alterados, todas as requisições incluem uma assinatura criptográfica.
Mecanismo: HMAC-SHA256.
Header:
X-SIGNATURE.
Exemplo de Implementação (Node.js)
Para validar o payload, calcule o hash HMAC-SHA256 do corpo bruto da requisição usando seu Segredo do Webhook e compare-o com o valor no cabeçalho:
JavaScript
const crypto = require('crypto'); // Certifique-se de usar o corpo bruto (raw body) da requisição const payload = JSON.stringify(request.body); const secret = 'seu_segredo_do_app'; const receivedSignature = request.headers['x-signature']; const expectedSignature = crypto.createHmac('sha256', secret) .update(payload) .digest('hex'); if (receivedSignature !== expectedSignature) { throw new Error('Assinatura inválida: a autenticidade do payload não pôde ser verificada.'); } // Prosseguir com a lógica do seu sistema