Skip to main content
O Webhook de Atendimento notifica seu sistema externo sempre que uma conversa é finalizada no Talk. A cada encerramento, o Talk envia um POST em JSON para a URL configurada, contendo os dados da conversa e do contato. Opcionalmente, o payload pode incluir o resumo gerado por IA, o histórico de mensagens e a nota CSAT. A configuração fica em Configurações → Webhooks → Finalização de Atendimento (talk.saninternet.com/settings/webhooks).
O disparo acontece quando a conversa é finalizada de fato. Isso inclui a finalização manual pelo atendente, o encerramento automático por inatividade e a finalização após a avaliação CSAT (com ou sem resposta do cliente).

Configuração

1

Ative o webhook

Em Configurações → Webhooks → Finalização de Atendimento, ligue a chave Ativar webhook.
2

Informe a URL de destino

O endpoint do seu sistema que receberá o POST. Use sempre https:// em produção.
3

Gere o secret de assinatura

Clique em Gerar novo e guarde o valor com segurança. Ele será usado para validar a autenticidade de cada entrega.
4

Escolha o conteúdo do payload

Conversa e contato são sempre enviados. Você pode incluir também o resumo da IA, o histórico de mensagens e a nota CSAT.
5

Defina o filtro de relevância (opcional)

Com Registrar apenas atendimentos relevantes ativo, conversas triviais (como um cumprimento sem continuação) não são enviadas ao seu sistema.
6

Teste a entrega

O botão Testar webhook envia um payload de exemplo (com test: true) para validar a integração antes de ativar.

Identificando o cliente: o ID externo

Para o seu sistema saber a qual cliente o atendimento pertence, cada contato do Talk possui um campo ID externo: um código livre que referencia o cliente no seu sistema (por exemplo, o ID dele no seu ERP ou CRM). O atendente define esse valor no painel de detalhes do contato, dentro do Inbox (seção Conversa, campo ID externo). Uma vez preenchido, ele acompanha o contato em todas as finalizações futuras e chega no payload como contact.externalId.
Quando o ID externo não estiver preenchido, contact.externalId chega como null. Nesse caso, use contact.phoneNumber como alternativa de vínculo.

Formato do payload

Campos especiais

Quando o resumo da IA está habilitado, a entrega aguarda a geração do resumo e pode atrasar alguns minutos em relação ao encerramento da conversa.

Entrega e resposta

  • O POST é enviado com Content-Type: application/json.
  • Seu endpoint deve responder com status 2xx em até 30 segundos.
  • Recomendação: receba, salve e responda. Deixe processamentos demorados para depois da resposta.

Headers enviados

Validando a assinatura

Toda entrega é assinada com HMAC-SHA256 usando o secret configurado. Recalcule o HMAC sobre o corpo bruto da requisição (antes do parse do JSON) e compare com o valor do header X-Webhook-Signature usando comparação de tempo constante. Requisições com assinatura inválida devem ser rejeitadas.
O secret nunca trafega nas requisições. Se ele vazar, gere um novo na tela de configuração e salve. As próximas entregas passam a usar o novo valor imediatamente.