Webhooks

Los Webhooks permiten integración en tiempo real entre Evolution API y WhatsApp™, permitiendo sincronización y compartición automatizada de datos. Es exactamente este recurso el que posibilita la creación de bots de autoatención y sistemas multi-servicio.

Activando Webhooks

Existen dos formas de activar el webhook:

En el archivo .env con eventos globales
Llamando al endpoint /webhook/instance

Eventos de webhook de la instancia

La mayoría de los usuarios preferirán la activación por instancia, de esta forma es más fácil controlar los eventos recibidos, sin embargo en algunos casos es necesario un webhook global, esto puede hacerse usando la variable de webhook global. Aquí hay un ejemplo con algunos eventos comunes escuchados:

/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	Obligatorio	Descripción
enabled	boolean	Sí	Ingrese “true” para crear o modificar datos del Webhook, o “false” si desea dejar de usarlo.
url	string	Sí	URL del Webhook para recibir datos del evento.
webhook_by_events	boolean	No	¿Desea generar una URL específica del Webhook para cada uno de sus eventos?
events	array	No	Lista de eventos a procesar. Si no desea usar algunos de estos eventos, simplemente elimínelos de la lista.

Es extremadamente necesario que el payload obedezca las reglas para crear un archivo JSON, considerando la disposición correcta de elementos, formato, corchetes, llaves y comas, etc. Antes de consumir el endpoint, si tiene dudas sobre el formato JSON, vaya a https://jsonlint.com/ y valide.

Eventos Globales de Webhook

Cada URL y eventos de Webhook de la instancia serán solicitados en el momento en que sean creados. Defina un webhook global que escuchará eventos habilitados de todas las instancias.

.env

WEBHOOK_GLOBAL_URL=''
WEBHOOK_GLOBAL_ENABLED=false

# Con esta opción activada, trabaja con una URL por evento de webhook, respetando la URL global y el nombre de cada evento
WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false

## Defina los eventos que desea escuchar, todos los eventos listados a continuación son soportados
WEBHOOK_EVENTS_APPLICATION_STARTUP=false
WEBHOOK_EVENTS_QRCODE_UPDATED=true

# Algunos eventos extras para errores
WEBHOOK_EVENTS_ERRORS=false
WEBHOOK_EVENTS_ERRORS_WEBHOOK=

Eventos Soportados

Estos son los eventos de webhook disponibles y soportados:

Variable de entorno	URL	Descripción
APPLICATION_STARTUP	/application-startup	Notifica cuando ocurre un inicio de aplicación
QRCODE_UPDATED	/qrcode-updated	Envía el base64 del qrcode para lectura
CONNECTION_UPDATE	/connection-update	Informa el estado de la conexión con WhatsApp
MESSAGES_SET	/messages-set	Envía una lista de todos sus mensajes cargados en WhatsApp. Este evento ocurre solo una vez
MESSAGES_UPSERT	/messages-upsert	Notifica cuando se recibe un mensaje
MESSAGES_UPDATE	/messages-update	Informa cuando un mensaje es actualizado
MESSAGES_DELETE	/messages-delete	Informa cuando un mensaje es eliminado
SEND_MESSAGE	/send-message	Notifica cuando un mensaje es enviado
CONTACTS_SET	/contacts-set	Realiza la carga inicial de todos los contactos. Este evento ocurre solo una vez
CONTACTS_UPSERT	/contacts-upsert	Recarga todos los contactos con información adicional. Este evento ocurre solo una vez
CONTACTS_UPDATE	/contacts-update	Informa cuando el contacto es actualizado
PRESENCE_UPDATE	/presence-update	Informa si el usuario está en línea, si está realizando alguna acción como escribir o grabar y su última vez visto: ‘no disponible’, ‘disponible’, ‘componiendo’, ‘grabando’, ‘pausado’
CHATS_SET	/chats-set	Envía una lista de todos los chats cargados
CHATS_UPDATE	/chats-update	Informa cuando el chat es actualizado
CHATS_UPSERT	/chats-upsert	Envía cualquier nueva información de chat
CHATS_DELETE	/chats-delete	Notifica cuando un chat es eliminado
GROUPS_UPSERT	/groups-upsert	Notifica cuando un grupo es creado
GROUPS_UPDATE	/groups-update	Notifica cuando un grupo tiene su información actualizada
GROUP_PARTICIPANTS_UPDATE	/group-participants-update	Notifica cuando una acción ocurre involucrando a un participante: ‘agregar’, ‘eliminar’, ‘promover’, ‘degradar’
NEW_TOKEN	/new-jwt	Notifica cuando el token (jwt) es actualizado

Webhook por eventos

Al habilitar las opciones WEBHOOK_BY_EVENTS en los webhooks globales y locales, las siguientes rutas serán agregadas al final del webhook.

Agregue al final de la URL el nombre del evento con un guion (-) entre las palabras que componen el evento.

Ejemplo

Suponiendo que su URL de webhook fuera https://sub.domain.com/webhook/. Evolution agregará automáticamente al final de la URL el nombre del evento cuando webhook_by_events esté definido como verdadero.

Evento	Nueva 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

Si es necesario, existe una opción para localizar cualquier webhook activo en la instancia específica.

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

Datos devueltos de la solicitud:

Llamando al endpoint devolverá toda la información sobre el webhook que está siendo usado por la instancia.

Resultado

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

Primeros Pasos

Configuración

Integraciones

Activando Webhooks

Eventos de webhook de la instancia

Parámetros

Eventos Globales de Webhook

Eventos Soportados

Webhook por eventos

Ejemplo

Localizando Webhook

Datos devueltos de la solicitud:

​Activando Webhooks

​Eventos de webhook de la instancia

​Parámetros

​Eventos Globales de Webhook

​Eventos Soportados

​Webhook por eventos

​Ejemplo

​Localizando Webhook

​Datos devueltos de la solicitud:

Activando Webhooks

Eventos de webhook de la instancia

Parámetros

Eventos Globales de Webhook

Eventos Soportados

Webhook por eventos

Ejemplo

Localizando Webhook

Datos devueltos de la solicitud: