A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá.
Quando usar
- Você quer registrar uma URL para receber eventos do Cloud Chat
- Você cadastrou um webhook e nada chega no seu endpoint
São dois caminhos diferentes
Escolher o caminho errado é a causa mais comum de webhook que não dispara.
1. Webhook de integração (o cadastro padrão)
Hoje o atalho para Webhooks não aparece na tela Configurações > Integrações. O cadastro continua funcionando: você acessa a tela direto pelo endereço, como abaixo.
- Entre no Cloud Chat com um usuário Administrador.
- Na barra de endereço do navegador, mantenha tudo até o número da conta (o que vem depois de
/accounts/) e troque o resto por/settings/integrations/webhook. Exemplo:.../app/accounts/123/dashboardvira.../app/accounts/123/settings/integrations/webhook. - Clique em Adicionar novo Webhook.
Você informa:
- URL do Webhook — o endpoint que vai receber o POST
- Eventos — quais assinar: conversa criada, conversa atualizada, status de conversa alterado, mensagem criada, mensagem atualizada, contato criado, contato atualizado, widget de chat aberto pelo usuário
Dá para cadastrar vários webhooks na mesma conta, cada um com sua URL e sua lista de eventos. Cada URL só pode ser cadastrada uma vez por conta: para assinar mais eventos no mesmo endpoint, edite o webhook que já existe.
Esse cadastro exige perfil Administrador. Com outro perfil, a tela de webhooks não abre.
2. Automação que dispara webhook
Configurações > Automação > Adicionar regra de automação
Aqui você não cadastra um webhook: cria uma regra com condições e escolhe a ação Enviar Evento Webhook, colando a URL no campo da ação.
Qual usar?
| Você quer... | Use |
|---|---|
| Receber todos os eventos de um tipo (ex.: toda mensagem criada) | Webhook de integração (caminho 1) |
| Receber só em casos específicos (ex.: só quando a conversa tem uma tag) | Automação com ação Enviar Evento Webhook |
Dá para distinguir os dois no seu endpoint pelo campo event do payload: o webhook de integração envia o nome do evento (ex.: message_created); a automação, com o payload padrão, envia com prefixo (ex.: automation_event.message_created). Se você preencheu um corpo customizado na ação da automação, chega exatamente o JSON que você definiu.
Um webhook de integração com "Mensagem criada" dispara em todas as mensagens da conta: de entrada e de saída, de todos os canais, incluindo notas privadas. Mensagens de atividade (as de sistema, como "conversa atribuída a…") não disparam. Se o volume for alto, prefira a automação com condições.
Observações
- Conversas que o Cloud Chat apenas espelha da ClaudIA (atendidas em outro helpdesk) não disparam webhook, em nenhum dos dois caminhos de integração.
- Caixas de entrada do tipo API têm um campo de URL de webhook próprio, nas configurações da caixa. Ele recebe os eventos daquela caixa, independentemente do cadastro do caminho 1.
- Referência completa dos payloads: docs.cloudhumans.com/api-reference.