![Visão geral de webhooks: cadastro do endpoint em Integrações, seleção dos eventos e envio de requisições POST para o sistema conectado.](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbHdRIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--14fa712b29db117fe3c20f64715ad0561ab0da15/1730735980-como-usar-webhooks.png)

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.

```json
{
  "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.