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
.envcom 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:
{
"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
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.
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.
{
"enabled": true,
"url": "[url]",
"webhookByEvents": false,
"events": [
[eventos]
]
}