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:

/webhook/instance

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

É 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/ 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

.env

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.

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`
QRCODE_UPDATED	`https://sub.domain.com/webhook/qrcode-updated`
CONNECTION_UPDATE	`https://sub.domain.com/webhook/connection-update`
MESSAGES_SET	`https://sub.domain.com/webhook/messages-set`
MESSAGES_UPSERT	`https://sub.domain.com/webhook/messages-upsert`
MESSAGES_UPDATE	`https://sub.domain.com/webhook/messages-update`
MESSAGES_DELETE	`https://sub.domain.com/webhook/messages-delete`
SEND_MESSAGE	`https://sub.domain.com/webhook/send-message`
CONTACTS_SET	`https://sub.domain.com/webhook/contacts-set`
CONTACTS_UPSERT	`https://sub.domain.com/webhook/contacts-upsert`
CONTACTS_UPDATE	`https://sub.domain.com/webhook/contacts-update`
PRESENCE_UPDATE	`https://sub.domain.com/webhook/presence-update`
CHATS_SET	`https://sub.domain.com/webhook/chats-set`
CHATS_UPDATE	`https://sub.domain.com/webhook/chats-update`
CHATS_UPSERT	`https://sub.domain.com/webhook/chats-upsert`
CHATS_DELETE	`https://sub.domain.com/webhook/chats-delete`
GROUPS_UPSERT	`https://sub.domain.com/webhook/groups-upsert`
GROUPS_UPDATE	`https://sub.domain.com/webhook/groups-update`
GROUP_PARTICIPANTS_UPDATE	`https://sub.domain.com/webhook/group-participants-update`
NEW_TOKEN	`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.

Resultado

{
  "enabled": true,
  "url": "[url]",
  "webhookByEvents": false,
  "events": [
    [eventos]
  ]
}

Primeiros Passos

Configuração

Integrações

Ativando Webhooks

Eventos de webhook da instância

Parâmetros

Eventos Globais de Webhook

Eventos Suportados

Webhook por eventos

Exemplo

Localizando Webhook

Dados retornados da solicitação:

​Ativando Webhooks

​Eventos de webhook da instância

​Parâmetros

​Eventos Globais de Webhook

​Eventos Suportados

​Webhook por eventos

​Exemplo

​Localizando Webhook

​Dados retornados da solicitação:

Ativando Webhooks

Eventos de webhook da instância

Parâmetros

Eventos Globais de Webhook

Eventos Suportados

Webhook por eventos

Exemplo

Localizando Webhook

Dados retornados da solicitação: