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âmetroTipoObrigatórioDescrição
enabledbooleanSimInsira “true” para criar ou alterar dados do Webhook, ou “false” se quiser parar de usá-lo.
urlstringSimURL do Webhook para receber dados do evento.
webhook_by_eventsbooleanNãoDeseja gerar uma URL específica do Webhook para cada um dos seus eventos.
eventsarrayNãoLista 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 ambienteURLDescrição
APPLICATION_STARTUP/application-startupNotifica quando uma inicialização de aplicativo ocorre
QRCODE_UPDATED/qrcode-updatedEnvia o base64 do qrcode para leitura
CONNECTION_UPDATE/connection-updateInforma o status da conexão com o WhatsApp
MESSAGES_SET/messages-setEnvia uma lista de todas as suas mensagens carregadas no WhatsApp. Este evento ocorre apenas uma vez
MESSAGES_UPSERT/messages-upsertNotifica quando uma mensagem é recebida
MESSAGES_UPDATE/messages-updateInforma quando uma mensagem é atualizada
MESSAGES_DELETE/messages-deleteInforma quando uma mensagem é excluída
SEND_MESSAGE/send-messageNotifica quando uma mensagem é enviada
CONTACTS_SET/contacts-setRealiza o carregamento inicial de todos os contatos. Este evento ocorre apenas uma vez
CONTACTS_UPSERT/contacts-upsertRecarrega todos os contatos com informações adicionais. Este evento ocorre apenas uma vez
CONTACTS_UPDATE/contacts-updateInforma quando o contato é atualizado
PRESENCE_UPDATE/presence-updateInforma 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-setEnvia uma lista de todos os chats carregados
CHATS_UPDATE/chats-updateInforma quando o chat é atualizado
CHATS_UPSERT/chats-upsertEnvia qualquer nova informação de chat
CHATS_DELETE/chats-deleteNotifica quando um chat é excluído
GROUPS_UPSERT/groups-upsertNotifica quando um grupo é criado
GROUPS_UPDATE/groups-updateNotifica quando um grupo tem suas informações atualizadas
GROUP_PARTICIPANTS_UPDATE/group-participants-updateNotifica quando uma ação ocorre envolvendo um participante: ‘adicionar’, ‘remover’, ‘promover’, ‘rebaixar’
NEW_TOKEN/new-jwtNotifica 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.

EventoNova URL de Webhook por Eventos
APPLICATION_STARTUPhttps://sub.domain.com/webhook/application-startup
QRCODE_UPDATEDhttps://sub.domain.com/webhook/qrcode-updated
CONNECTION_UPDATEhttps://sub.domain.com/webhook/connection-update
MESSAGES_SEThttps://sub.domain.com/webhook/messages-set
MESSAGES_UPSERThttps://sub.domain.com/webhook/messages-upsert
MESSAGES_UPDATEhttps://sub.domain.com/webhook/messages-update
MESSAGES_DELETEhttps://sub.domain.com/webhook/messages-delete
SEND_MESSAGEhttps://sub.domain.com/webhook/send-message
CONTACTS_SEThttps://sub.domain.com/webhook/contacts-set
CONTACTS_UPSERThttps://sub.domain.com/webhook/contacts-upsert
CONTACTS_UPDATEhttps://sub.domain.com/webhook/contacts-update
PRESENCE_UPDATEhttps://sub.domain.com/webhook/presence-update
CHATS_SEThttps://sub.domain.com/webhook/chats-set
CHATS_UPDATEhttps://sub.domain.com/webhook/chats-update
CHATS_UPSERThttps://sub.domain.com/webhook/chats-upsert
CHATS_DELETEhttps://sub.domain.com/webhook/chats-delete
GROUPS_UPSERThttps://sub.domain.com/webhook/groups-upsert
GROUPS_UPDATEhttps://sub.domain.com/webhook/groups-update
GROUP_PARTICIPANTS_UPDATEhttps://sub.domain.com/webhook/group-participants-update
NEW_TOKENhttps://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étodoEndpoint
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]
  ]
}
Recursos Disponíveis