Webhooks são callbacks HTTP configurados para cada conta, disparados quando ações como criação de mensagens ocorrem no Chatwoot. É possível configurar múltiplos webhooks para uma única conta.

### **Como adicionar um webhook?**

**Passo 1**: Vá para Configurações → Integrações → Webhooks e clique no botão "Configurar".

![](https://atendimento.chatwoot.app.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbVUyIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--14eaa8d3e13f6420036d9d5144b8b82afc43c5e3/Captura%20de%20Tela%202025-06-23%20a%CC%80s%2010.20.25.png)

**Passo 2**: Clique no botão "Adicionar novo webhook". Uma janela modal será aberta, onde você deve inserir a URL para a qual a requisição POST será enviada. Depois, selecione os eventos que deseja assinar, para que apenas eventos relevantes no Chatwoot sejam notificados.

![](https://atendimento.chatwoot.app.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbWMyIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--365063de9259e92f379863fa664cc6a28aeb81ce/Captura%20de%20Tela%202025-06-23%20a%CC%80s%2010.23.48.png)

O Chatwoot enviará uma requisição POST com o seguinte payload para as URLs configuradas, quando ocorrerem atualizações em sua conta.

### **Exemplo de payload de webhook:**

```

{

  "event": "message_created", // Nome do evento

  "id": "1", // ID da mensagem

  "content": "Oi", // Conteúdo da mensagem

  "created_at": "2020-03-03 13:05:57 UTC", // Data e hora em que a mensagem foi enviada

  "message_type": "incoming", // Pode ser incoming (entrada), outgoing (saída) ou template

  "content_type": "enum", // Pode ser input_select, cards, form ou texto. O valor padrão é texto

  "content_attributes": {}, // Atributos do conteúdo, podem variar

  "source_id": "", // ID externo se for uma integração com Twitter ou Facebook

  "sender": { // Detalhes do agente que enviou a mensagem

    "id": "1",

    "name": "Agente",

    "email": "agent@example.com"

  },

  "contact": { // Detalhes do usuário que enviou a mensagem

    "id": "1",

    "name": "nome-do-contato"

  },

  "conversation": { // Detalhes da conversa

    "display_id": "1", // ID da conversa visível no painel

    "additional_attributes": {

      "browser": {

        "device_name": "Macbook",

        "browser_name": "Chrome",

        "platform_name": "Macintosh",

        "browser_version": "80.0.3987.122",

        "platform_version": "10.15.2"

      },

      "referer": "<http://www.chatwoot.com>",

      "initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)"

    }

  },

  "account": { // Detalhes da conta

    "id": "1",

    "name": "Chatwoot"

  }

}
```

### **Eventos de webhook suportados no Chatwoot**

O Chatwoot publica vários eventos para os endpoints de webhooks configurados. Cada evento tem sua estrutura de payload baseada no tipo de modelo a que se refere. A seguir, estão descritos os principais objetos usados no Chatwoot e seus atributos.

#### **Objetos**

Um payload de evento pode incluir os seguintes objetos. Os vários tipos de objetos suportados pelo Chatwoot estão listados abaixo.

* **Conta (Account)**:

  ```
  {
    "id": "integer",
    "name": "string"
  }
  
  ```

* **Caixa de Entrada (Inbox)**:

  ```
  {
    "id": "integer",
    "name": "string"
  }
  
  ```

* **Contato (Contact)**:

  ```
  {
    "id": "integer",
    "name": "string",
    "avatar": "string",
    "type": "contact",
    "account": {
      // <...Account Object>
    }
  }
  
  ```

* **Usuário (User)**:

  ```
  {
    "id": "integer",
    "name": "string",
    "email": "string",
    "type": "user"
  }
  
  ```

* **Conversa (Conversation)**:

  ```
  {
    "additional_attributes": {
      "browser": {
        "device_name": "string",
        "browser_name": "string",
        "platform_name": "string",
        "browser_version": "string",
        "platform_version": "string"
      },
      "referer": "string",
      "initiated_at": {
        "timestamp": "iso-datetime"
      }
    },
    "can_reply": "boolean",
    "channel": "string",
    "id": "integer",
    "inbox_id": "integer",
    "contact_inbox": {
      "id": "integer",
      "contact_id": "integer",
      "inbox_id": "integer",
      "source_id": "string",
      "created_at": "datetime",
      "updated_at": "datetime",
      "hmac_verified": "boolean"
    },
    "messages": ["Array of message objects"],
    "meta": {
      "sender": {
        // Contact Object
      },
      "assignee": {
        // User Object
      }
    },
    "status": "string",
    "unread_count": "integer",
    "agent_last_seen_at": "unix-timestamp",
    "contact_last_seen_at": "unix-timestamp",
    "timestamp": "unix-timestamp",
    "account_id": "integer"
  }
  
  ```

* **Mensagem (Message)**:

  ```
  {
    "id": "integer",
    "content": "string",
    "message_type": "integer",
    "created_at": "unix-timestamp",
    "private": "boolean",
    "source_id": "string / null",
    "content_type": "string",
    "content_attributes": "object",
    "sender": {
      "type": "string - contact/user"
      // User or Contact Object
    },
    "account": {
      // Account Object
    },
    "conversation": {
      // Conversation Object
    },
    "inbox": {
      // Inbox Object
    }
  }
  
  ```

* **Uma carga útil de webhook de amostra**:

  ```
  {
    "event": "event_name"
    // Attributes related to the event
  }
  
  ```

### **Eventos Webhook**

Chatwoot suporta os seguintes eventos webhook. Você pode assiná-los ao configurar um webhook no painel ou usando a API.

### **conversation_criado: Disparado quando uma nova conversa é criada.**

Este evento será acionado quando uma nova conversa for criada na conta. A carga útil para o evento é a seguinte.

```
{
  "event": "conversation_created"
  // <...Conversation Attributes>
}
```

### **conversação_atualizado**

Este evento será acionado quando houver uma alteração em qualquer um dos atributos na conversa.

```
{
  "event": "conversation_updated",
  "changed_attributes": [
    {
      "<attribute_name>": {
        "current_value": "",
        "previous_value": ""
      }
    }
  ]
  // <...Conversation Attributes>
}
```

### **conversation_status_alterado**

Este evento será acionado quando o status da conversa for alterado.

Observação: Se você estiver usando APIs de bot de agente em vez de webhooks, esse evento ainda não é suportado.

```
{
  "event": "conversation_status_changed"
  // <...Conversation Attributes>
}
```

### **message_criado**

Esse evento será acionado quando uma mensagem for criada em uma conversa. A carga útil para o evento é a seguinte.

```
{
  "event": "message_created"
  // <...Message Attributes>
}
```

### **mensagem_atualizado**

Este evento será acionado quando uma mensagem for atualizada em uma conversa. A carga útil para o evento é a seguinte.

```
{
  "event": "message_updated"
  // <...Message Attributes>
}
```

### **webwidget_triggered**

Este evento será acionado quando o usuário final abrir o widget de bate-papo ao vivo.

```
{
  "id": ,
  "contact": {
    // <...Contact Object>
  },
  "inbox": {
    // <...Inbox Object>
  },
  "account": {
    // <...Account Object>
  },
  "current_conversation": {
    // <...Conversation Object>
  },
  "source_id": "string",
  "event": "webwidget_triggered",
  "event_info": {
    "initiated_at": {
      "timestamp": "date-string"
    },
    "referer": "string",
    "widget_language": "string",
    "browser_language": "string",
    "browser": {
      "browser_name": "string",
      "browser_version": "string",
      "device_name": "string",
      "platform_name": "string",
      "platform_version": "string"
    }
  }
}
```

   
Créditos: https://chatwoot.app.br/