> ## Documentation Index
> Fetch the complete documentation index at: https://doc.evolution-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

Os Webhooks permitem integração em tempo real entre a Evolution API e o WhatsApp™, permitindo sincronização e compartilhamento automatizados de dados.

É exatamente esse recurso que possibilita a criação de bots de autoatendimento e sistemas multi-serviço.

## Ativando Webhooks

Existem duas maneiras de ativar o webhook:

* No arquivo `.env` com eventos globais
* Chamando o endpoint `/webhook/instance`

### Eventos de webhook da instância

A maioria dos usuários preferirá a ativação por instância, desta forma é mais fácil controlar os eventos recebidos, no entanto em alguns casos é necessário um webhook global,
isso pode ser feito usando a variável de webhook global.

Aqui está um exemplo com alguns eventos comuns ouvidos:

```json /webhook/instance theme={null}
{
  "url": "{{webhookUrl}}",
  "webhook_by_events": false,
  "webhook_base64": false,
  "events": [
      "QRCODE_UPDATED",
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "MESSAGES_DELETE",
      "SEND_MESSAGE",
      "CONNECTION_UPDATE",
      "TYPEBOT_START",
      "TYPEBOT_CHANGE_STATUS"
  ]    
}
```

### Parâmetros

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| enabled | boolean | Sim | Insira "true" para criar ou alterar dados do Webhook, ou "false" se quiser parar de usá-lo. |
| url | string | Sim | URL do Webhook para receber dados do evento. |
| webhook\_by\_events | boolean | Não | Deseja gerar uma URL específica do Webhook para cada um dos seus eventos. |
| events | array | Não | Lista de eventos a serem processados. Se você não quiser usar alguns desses eventos, apenas remova-os da lista. |

> [!NOTE]
>
> É extremamente necessário que o payload obedeça às regras para criar um arquivo JSON, considerando o arranjo correto de itens, formatação, colchetes, chaves e vírgulas, etc.
> Antes de consumir o endpoint, se tiver dúvidas sobre a formatação JSON, vá para [https://jsonlint.com/](https://jsonlint.com/) e valide.

### Eventos Globais de Webhook

Cada URL e eventos de Webhook da instância serão solicitados no momento em que forem criados
Defina um webhook global que ouvirá eventos habilitados de todas as instâncias

```bash .env theme={null}
WEBHOOK_GLOBAL_URL=''
WEBHOOK_GLOBAL_ENABLED=false

# Com esta opção ativada, você trabalha com uma URL por evento de webhook, respeitando a URL global e o nome de cada evento
WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false

## Defina os eventos que você deseja ouvir, todos os eventos listados abaixo são suportados
WEBHOOK_EVENTS_APPLICATION_STARTUP=false
WEBHOOK_EVENTS_QRCODE_UPDATED=true

# Alguns eventos extras para erros
WEBHOOK_EVENTS_ERRORS=false
WEBHOOK_EVENTS_ERRORS_WEBHOOK=
```

## Eventos Suportados

Estes são os eventos de webhook disponíveis e suportados:

| **Variável de ambiente** | **URL** | **Descrição** |
| - | - | - |
| APPLICATION\_STARTUP | /application-startup | Notifica quando uma inicialização de aplicativo ocorre |
| QRCODE\_UPDATED | /qrcode-updated | Envia o base64 do qrcode para leitura |
| CONNECTION\_UPDATE | /connection-update | Informa o status da conexão com o WhatsApp |
| MESSAGES\_SET | /messages-set | Envia uma lista de todas as suas mensagens carregadas no WhatsApp. Este evento ocorre apenas uma vez |
| MESSAGES\_UPSERT | /messages-upsert | Notifica quando uma mensagem é recebida |
| MESSAGES\_UPDATE | /messages-update | Informa quando uma mensagem é atualizada |
| MESSAGES\_DELETE | /messages-delete | Informa quando uma mensagem é excluída |
| SEND\_MESSAGE | /send-message | Notifica quando uma mensagem é enviada |
| CONTACTS\_SET | /contacts-set | Realiza o carregamento inicial de todos os contatos. Este evento ocorre apenas uma vez |
| CONTACTS\_UPSERT | /contacts-upsert | Recarrega todos os contatos com informações adicionais. Este evento ocorre apenas uma vez |
| CONTACTS\_UPDATE | /contacts-update | Informa quando o contato é atualizado |
| PRESENCE\_UPDATE | /presence-update | Informa se o usuário está online, se ele está realizando alguma ação como escrever ou gravar e seu último visto: 'indisponível', 'disponível', 'compondo', 'gravando', 'pausado' |
| CHATS\_SET | /chats-set | Envia uma lista de todos os chats carregados |
| CHATS\_UPDATE | /chats-update | Informa quando o chat é atualizado |
| CHATS\_UPSERT | /chats-upsert | Envia qualquer nova informação de chat |
| CHATS\_DELETE | /chats-delete | Notifica quando um chat é excluído |
| GROUPS\_UPSERT | /groups-upsert | Notifica quando um grupo é criado |
| GROUPS\_UPDATE | /groups-update | Notifica quando um grupo tem suas informações atualizadas |
| GROUP\_PARTICIPANTS\_UPDATE | /group-participants-update | Notifica quando uma ação ocorre envolvendo um participante: 'adicionar', 'remover', 'promover', 'rebaixar' |
| NEW\_TOKEN | /new-jwt | Notifica quando o token (jwt) é atualizado |

## Webhook por eventos

Ao habilitar as opções WEBHOOK\_BY\_EVENTS nos webhooks globais e locais, os seguintes caminhos serão adicionados ao final do webhook.

> [!NOTE]
>
> Adicione ao final da URL o nome do evento com um traço (-) entre as palavras que compõem o evento.

### Exemplo

Supondo que sua URL de webhook fosse `https://sub.domain.com/webhook/`. A Evolution adicionará automaticamente ao final da URL o nome do evento quando `webhook_by_events` estiver definido como verdadeiro.

| **Evento** | **Nova URL de Webhook por Eventos** |
| - | - |
| APPLICATION\_STARTUP | [https://sub.domain.com/webhook/application-startup](https://sub.domain.com/webhook/application-startup) |
| QRCODE\_UPDATED | [https://sub.domain.com/webhook/qrcode-updated](https://sub.domain.com/webhook/qrcode-updated) |
| CONNECTION\_UPDATE | [https://sub.domain.com/webhook/connection-update](https://sub.domain.com/webhook/connection-update) |
| MESSAGES\_SET | [https://sub.domain.com/webhook/messages-set](https://sub.domain.com/webhook/messages-set) |
| MESSAGES\_UPSERT | [https://sub.domain.com/webhook/messages-upsert](https://sub.domain.com/webhook/messages-upsert) |
| MESSAGES\_UPDATE | [https://sub.domain.com/webhook/messages-update](https://sub.domain.com/webhook/messages-update) |
| MESSAGES\_DELETE | [https://sub.domain.com/webhook/messages-delete](https://sub.domain.com/webhook/messages-delete) |
| SEND\_MESSAGE | [https://sub.domain.com/webhook/send-message](https://sub.domain.com/webhook/send-message) |
| CONTACTS\_SET | [https://sub.domain.com/webhook/contacts-set](https://sub.domain.com/webhook/contacts-set) |
| CONTACTS\_UPSERT | [https://sub.domain.com/webhook/contacts-upsert](https://sub.domain.com/webhook/contacts-upsert) |
| CONTACTS\_UPDATE | [https://sub.domain.com/webhook/contacts-update](https://sub.domain.com/webhook/contacts-update) |
| PRESENCE\_UPDATE | [https://sub.domain.com/webhook/presence-update](https://sub.domain.com/webhook/presence-update) |
| CHATS\_SET | [https://sub.domain.com/webhook/chats-set](https://sub.domain.com/webhook/chats-set) |
| CHATS\_UPDATE | [https://sub.domain.com/webhook/chats-update](https://sub.domain.com/webhook/chats-update) |
| CHATS\_UPSERT | [https://sub.domain.com/webhook/chats-upsert](https://sub.domain.com/webhook/chats-upsert) |
| CHATS\_DELETE | [https://sub.domain.com/webhook/chats-delete](https://sub.domain.com/webhook/chats-delete) |
| GROUPS\_UPSERT | [https://sub.domain.com/webhook/groups-upsert](https://sub.domain.com/webhook/groups-upsert) |
| GROUPS\_UPDATE | [https://sub.domain.com/webhook/groups-update](https://sub.domain.com/webhook/groups-update) |
| GROUP\_PARTICIPANTS\_UPDATE | [https://sub.domain.com/webhook/group-participants-update](https://sub.domain.com/webhook/group-participants-update) |
| NEW\_TOKEN | [https://sub.domain.com/webhook/new-jwt](https://sub.domain.com/webhook/new-jwt) |

## Localizando Webhook

Se necessário, há uma opção para localizar qualquer webhook ativo na instância específica.

| Método | Endpoint |
| - | - |
| GET | \[baseUrl]/webhook/find/\[instance] |

### Dados retornados da solicitação:

Chamando o endpoint retornará todas as informações sobre o webhook que está sendo usado pela instância.

```json Resultado theme={null}
{
  "enabled": true,
  "url": "[url]",
  "webhookByEvents": false,
  "events": [
    [eventos]
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.