Como usar webhooks?
Webhooks são callbacks HTTP configurados para cada conta. Eles são acionados quando ações como a criação de uma mensagem ocorrem no Talk. Vários webhooks podem ser criados para uma única conta.
Passo 1. Acesse Configurações → Integrações → Webhooks. Clique no botão "Configurar".
Passo 2. Clique no botão "Adicionar novo webhook". Um modal será aberto. Aqui, insira a URL para a qual a requisição POST deve ser enviada. Em seguida, você precisa selecionar os eventos aos quais deseja se inscrever. Esta opção permite que você escute apenas pelos eventos relevantes no Talk.
O Talk enviará uma requisição POST com o seguinte payload para as URLs configuradas para diversas atualizações em sua conta.
O Talk publica vários eventos para os endpoints de webhook configurados. Se você quiser configurar um webhook, consulte o guia aqui.
Cada evento possui sua estrutura de payload com base no tipo de modelo sobre o qual atuam. A seção a seguir descreve os principais objetos que usamos no Talk e seus atributos.
Um payload de evento pode incluir qualquer um dos seguintes objetos. Os vários tipos de objetos suportados pelo Talk estão listados abaixo.
Conta
Caixa de entrada
Contato
Usuário
Conversa
Mensagem
Exemplo de payload de webhook
O Talk suporta os seguintes eventos de webhook. Você pode se inscrever neles ao configurar um webhook no painel ou utilizando a API.
Este evento será acionado quando uma nova conversa for criada na conta. O payload do evento é o seguinte.
Este evento será acionado quando houver uma alteração em algum dos atributos da conversa.
Este evento será acionado quando o status da conversa for alterado.
Nota: Se você estiver utilizando APIs de agent bot em vez de webhooks, este evento ainda não é suportado.
Este evento será acionado quando uma mensagem for criada em uma conversa. O payload do evento é o seguinte.
Este evento será acionado quando uma mensagem for atualizada em uma conversa. O payload do evento é o seguinte.
Este evento será acionado quando o usuário final abrir o widget de chat ao vivo.
Este evento é acionado quando um agente começa a digitar em uma conversa. Pode ser uma nota privada ou uma mensagem para o cliente. Você pode usar o flag is_private para diferenciar entre os dois.
Este evento é acionado quando o agente para de digitar ou sai da janela da conversa.
O Talk assina todas as requisições de webhook de saída para que seu servidor possa verificar se o payload foi enviado pelo Talk e não foi adulterado. O segredo é exibido uma vez que o webhook é criado, e você pode visualizá-lo novamente no formulário de edição do webhook.
Toda requisição de webhook envia os seguintes cabeçalhos, que podem ser usados para calcular a assinatura HMAC do payload
X-Talk-Signature: assinatura HMAC-SHA256 prefixada com sha256=
X-Talk-Timestamp: timestamp Unix (segundos) de quando a requisição foi assinada
X-Talk-Delivery: ID único de entrega para o evento de webhook (quando disponível)
A assinatura é calculada assim:
Onde:
webhook_secret é o segredo associado ao webhook
timestamp é o valor do cabeçalho X-Talk-Timestamp
raw_body é o corpo da requisição JSON bruta (não parseado/re-serializado)
Extraia X-Talk-Signature e X-Talk-Timestamp dos cabeçalhos da requisição
Leia o corpo bruno da requisição como bytes (não parse e re-serialize)
Calcule a assinatura esperada: sha256=HMAC-SHA256(secret, "{timestamp}.{raw_body}")
Compare a assinatura calculada com a recebida usando uma comparação em tempo constante
Opcionalmente, rejeite requisições cujo timestamp seja muito antigo para prevenir ataques de repetição (replay)
Sempre utilize o corpo bruto da requisição para verificação. Fazer o parse do JSON e depois re-serializar pode alterar a ordenação das chaves, espaços ou escape unicode, o que resultará em uma assinatura diferente.
Sempre utilize comparação em tempo constante (ex: hmac.compare_digest, crypto.timingSafeEqual, ActiveSupport::SecurityUtils.secure_compare) para prevenir ataques de timing.
Considere rejeitar requisições com timestamp mais antigos que 5 minutos para mitigar ataques de repetição.