Como usar webhooks?

Webhooks são requisições HTTP enviadas pela plataforma quando ocorre um evento na sua conta, como a criação de uma mensagem ou a atualização de um contato. Você pode cadastrar mais de um endpoint e escolher quais eventos cada um receberá.

Adicionar um webhook

1. Acesse Configurações → Integrações → Webhooks e clique em Configurar.
2. Clique em Adicionar novo webhook.
3. Informe um nome e uma URL pública iniciada por https://.
4. Selecione somente os eventos que a sua integração precisa receber.
5. Salve o webhook e guarde o segredo exibido para validar as entregas no seu servidor.

O endpoint deve aceitar requisições POST, responder rapidamente com um código 2xx e processar tarefas demoradas em segundo plano. Considere que o mesmo evento pode ser entregue novamente: use o identificador do recurso para tornar o processamento idempotente.

Exemplo de payload

Este é um exemplo reduzido de message_created. Os campos podem variar conforme o canal, o tipo de mensagem e os recursos habilitados.

{
  "event": "message_created",
  "id": 42,
  "content": "Olá, preciso de ajuda",
  "created_at": "2026-07-10T12:30:00.000Z",
  "message_type": "incoming",
  "content_type": "text",
  "private": false,
  "content_attributes": {},
  "source_id": "identificador-no-canal",
  "sender": {
    "id": 81,
    "name": "Maria"
  },
  "conversation": {
    "id": 123,
    "display_id": 57,
    "status": "open"
  },
  "inbox": {
    "id": 9,
    "name": "Atendimento"
  },
  "account": {
    "id": 1,
    "name": "Minha conta"
  }
}

O campo message_type pode ser incoming, outgoing, activity ou template. O content_type descreve o formato e pode assumir valores como text, input_text, input_textarea, input_email, input_select, cards, form, article, incoming_email, input_csat, integrations, sticker ou voice_call.

Não faça o consumidor depender de um exemplo inteiro e imutável: leia apenas os campos necessários e tolere campos adicionais.

Eventos disponíveis no painel

• conversation_created — uma conversa foi criada.
• conversation_status_changed — o status da conversa mudou.
• conversation_updated — um atributo da conversa mudou; o payload inclui changed_attributes.
• message_created — uma mensagem foi criada.
• message_updated — uma mensagem foi atualizada.
• webwidget_triggered — o visitante abriu o widget de chat do site.
• contact_created — um contato foi criado.
• contact_updated — um contato foi atualizado; o payload inclui changed_attributes.
• conversation_typing_on — alguém começou a digitar.
• conversation_typing_off — alguém parou de digitar.
• inbox_updated — uma caixa de entrada foi atualizada; aparece quando os eventos de caixa estão habilitados na conta.

Os bots de agente também recebem eventos de conversa, incluindo conversation_status_changed, pela URL configurada no próprio bot. Webhooks da conta e webhooks de bots são configurações diferentes.

Boas práticas de segurança

• Use somente HTTPS com certificado válido.
• Verifique a assinatura usando o segredo do webhook antes de confiar no corpo recebido.
• Nunca coloque tokens de acesso ou credenciais na URL.
• Registre falhas sem gravar dados sensíveis desnecessários.
• Trate payloads como entrada externa: valide tipos, limites e campos obrigatórios.

Para alterar os eventos ou a URL, volte a Configurações → Integrações → Webhooks, edite o endpoint e salve novamente.