Webhooks - Documentação do Evolution Foundation

Los Webhooks permiten que Evolution Go envíe notificaciones en tiempo real a su aplicación cuando ocurren eventos en WhatsApp, como recepción de mensajes, actualizaciones de conexión, llamadas y más.

Guía Rápida

Siga estos pasos para configurar y recibir webhooks de Evolution Go.

Prerrequisitos

Antes de configurar webhooks, necesita:

Tener Evolution Go instalado y ejecutándose — vea la guía de instalación
Tener una instancia creada — vea Primeros Pasos
Tener su API Key (GLOBAL_API_KEY configurada en .env)
Tener una URL accesible para recibir los eventos

Para pruebas rápidas, use webhook.site para generar una URL temporal y visualizar los eventos recibidos en tiempo real. Para desarrollo local, use ngrok para exponer su servidor local a internet.

Paso 1: Conectar la instancia con webhook

Configure el webhook al conectar su instancia enviando una solicitud al endpoint de conexión.

Método

POST {BASE_URL}/instance/connect

Key	Value	Descripción
Content-Type	`application/json`	Tipo de contenido
apikey	`SU_GLOBAL_API_KEY`	Clave de API global configurada en `.env`
instanceId	`249aad2e-68f9-464f-bc84-aca560c38f0e`	UUID de la instancia que desea conectar

La API Key es el valor de la variable GLOBAL_API_KEY configurada en el archivo .env de Evolution Go. Nunca exponga esta clave públicamente. Vea más detalles en Primeros Pasos.

Body

{
  "webhookUrl": "https://webhook.site/su-id-unico",
  "subscribe": ["ALL"],
  "immediate": true
}

Ejemplo con cURL

curl -X POST 'http://localhost:8080/instance/connect' \
  -H 'Content-Type: application/json' \
  -H 'apikey: SU_GLOBAL_API_KEY' \
  -H 'instanceId: 249aad2e-68f9-464f-bc84-aca560c38f0e' \
  -d '{
    "webhookUrl": "https://webhook.site/su-id-unico",
    "subscribe": ["ALL"],
    "immediate": true
  }'

Ejemplo con JavaScript

const response = await fetch('http://localhost:8080/instance/connect', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'SU_GLOBAL_API_KEY',
    'instanceId': '249aad2e-68f9-464f-bc84-aca560c38f0e'
  },
  body: JSON.stringify({
    webhookUrl: 'https://webhook.site/su-id-unico',
    subscribe: ['ALL'],
    immediate: true
  })
});

const data = await response.json();
console.log(data);

Ejemplo con Python

import requests

response = requests.post(
    'http://localhost:8080/instance/connect',
    headers={
        'Content-Type': 'application/json',
        'apikey': 'SU_GLOBAL_API_KEY',
        'instanceId': '249aad2e-68f9-464f-bc84-aca560c38f0e'
    },
    json={
        'webhookUrl': 'https://webhook.site/su-id-unico',
        'subscribe': ['ALL'],
        'immediate': True
    }
)

print(response.json())

Paso 2: Emparejar con WhatsApp

Después de la conexión, recibirá un evento QRCode en su webhook con la imagen del QR Code en base64:

Abra WhatsApp en su celular
Vaya a Configuración > Dispositivos vinculados > Vincular un dispositivo
Escanee el QR Code recibido en su webhook (decodifique el campo qrcode base64 para mostrar la imagen)

Si prefiere usar Pairing Code en vez de QR Code, envíe el campo phone en el body:

{
  "webhookUrl": "https://webhook.site/su-id-unico",
  "subscribe": ["ALL"],
  "phone": "5511999999999"
}

Paso 3: Confirmar la conexión

Después del emparejamiento exitoso, recibirá una secuencia de eventos: PairSuccess → Connected → OfflineSyncCompleted. Si recibió estos 3 eventos, su webhook está correctamente configurado.

Paso 4: Recibir mensajes

A partir de ahora, cada mensaje recibido en WhatsApp será enviado como evento Message a su URL.

Usuario envía mensaje → WhatsApp → Evolution Go → HTTP POST → Su Webhook

Procesando en su servidor

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { event, data, instanceId } = req.body;

  switch (event) {
    case 'Message':
      const sender = data.Info.PushName || data.Info.Sender;
      const text = data.Message.conversation;
      console.log(`[${instanceId}] ${sender}: ${text}`);
      break;
    case 'Connected':
      console.log(`Instancia ${instanceId} conectada!`);
      break;
    case 'QRCode':
      console.log(`QR Code recibido para ${instanceId}`);
      break;
    default:
      console.log(`Evento: ${event}`);
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook ejecutándose en el puerto 3000'));

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.json
    event = payload.get('event')
    data = payload.get('data', {})
    instance_id = payload.get('instanceId')

    if event == 'Message':
        sender = data.get('Info', {}).get('PushName', data.get('Info', {}).get('Sender'))
        text = data.get('Message', {}).get('conversation', '')
        print(f'[{instance_id}] {sender}: {text}')
    elif event == 'Connected':
        print(f'Instancia {instance_id} conectada!')
    elif event == 'QRCode':
        print(f'QR Code recibido para {instance_id}')
    else:
        print(f'Evento: {event}')

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Su endpoint debe responder con estado HTTP 2xx (200-299) en hasta 30 segundos. De lo contrario, Evolution Go realizará hasta 5 reintentos con un intervalo de 30 segundos entre cada uno.

Configuración Detallada

La configuración de webhooks se realiza al momento de conectar la instancia, a través del endpoint POST /instance/connect.

Webhook por Instancia

Al conectar una instancia, puede definir la URL del webhook y los eventos que desea recibir:

POST /instance/connect

{
  "webhookUrl": "https://su-dominio.com/webhook",
  "subscribe": [
    "MESSAGE",
    "SEND_MESSAGE",
    "CONNECTION",
    "QRCODE"
  ],
  "immediate": true,
  "phone": "5511999999999"
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
webhookUrl	string	No	URL que recibirá los eventos via HTTP POST
subscribe	string[]	No	Lista de tipos de eventos a recibir. Si está vacío, solo recibe `MESSAGE`
immediate	boolean	No	Conectar inmediatamente sin esperar QR Code
phone	string	No	Número de teléfono para emparejamiento
rabbitmqEnable	string	No	`"enabled"` para activar envío via RabbitMQ
websocketEnable	string	No	`"enabled"` para activar envío via WebSocket
natsEnable	string	No	`"enabled"` para activar envío via NATS

Webhook Global

Puede definir un webhook global mediante variable de entorno. Recibirá eventos de todas las instancias, además de los webhooks individuales de cada instancia.

.env

# URL del webhook global (recibe eventos de todas las instancias)
WEBHOOK_URL=https://su-dominio.com/webhook/global

# Incluir archivos multimedia en el payload del webhook (predeterminado: true)
WEBHOOK_FILES=true

Cuando están configurados, ambos webhooks se activan: el global (definido por WEBHOOK_URL) y el de la instancia (definido en webhookUrl). Esto permite tener un sistema centralizado de monitoreo junto con integraciones específicas por instancia.

Tipos de Eventos

Al configurar el webhook, puede suscribirse a los siguientes tipos de eventos:

Tipo de Evento	Descripción	Eventos Incluidos
`ALL`	Recibe todos los eventos disponibles	Todos los siguientes
`MESSAGE`	Mensajes recibidos	`Message`
`SEND_MESSAGE`	Mensajes enviados	`SendMessage`
`READ_RECEIPT`	Confirmaciones de lectura	`Receipt` (Read, ReadSelf, Delivered)
`PRESENCE`	Estado de presencia online/offline	`Presence`
`HISTORY_SYNC`	Sincronización de historial	`HistorySync`
`CHAT_PRESENCE`	Presencia en chats (escribiendo, grabando)	`ChatPresence`, `Archive`
`CALL`	Eventos de llamada	`CallOffer`, `CallRelayLatency`, `CallTerminate`
`CONNECTION`	Estado de conexión	`Connected`, `PairSuccess`, `LoggedOut`, `OfflineSyncCompleted`
`LABEL`	Gestión de etiquetas	`LabelEdit`, `LabelAssociationChat`, `LabelAssociationMessage`
`CONTACT`	Actualizaciones de contactos	`Contact`, `PushName`
`GROUP`	Eventos de grupos	`GroupInfo`, `JoinedGroup`
`NEWSLETTER`	Eventos de canales/newsletters	`NewsletterJoin`, `NewsletterLeave`
`QRCODE`	Eventos de QR Code	`QRCode`, `QRTimeout`, `QRSuccess`

Use "ALL" en la lista de subscribe para recibir todos los eventos sin necesidad de listar cada uno individualmente.

Estructura del Payload

Todos los webhooks se envían como solicitudes HTTP POST con Content-Type: application/json. La estructura base del payload es:

{
  "event": "NombreDelEvento",
  "data": { ... },
  "instanceId": "uuid-de-la-instancia",
  "instanceToken": "token_de_la_instancia"
}

Campo	Tipo	Descripción
event	string	Nombre del evento que ocurrió
data	object	Datos específicos del evento (varía por evento)
instanceId	string	UUID de la instancia
instanceToken	string	Token de autenticación de la instancia

Payloads por Evento

QRCode

Emitido cuando se genera un nuevo QR Code para emparejamiento.

{
  "event": "QRCode",
  "data": {
    "code": "2@DoOPPlssTlSoDDdtPFXDXNp24ImY0bxwSivPLNbNLtCgXOYGFnsCN1Y64QYQB/r5tAmNqt0zhaf3TyOydXGZYGnKqB3UNTPDx1M=,...",
    "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA..."
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.code	string	Código del QR Code para emparejamiento
data.qrcode	string	Imagen del QR Code en base64 (PNG)

PairSuccess

Emitido cuando el emparejamiento del dispositivo se completa exitosamente.

{
  "event": "PairSuccess",
  "data": {
    "BusinessName": "",
    "ID": "5511918798714:[email protected]",
    "Platform": "android",
    "jid": "5511918798714:[email protected]",
    "pushName": "",
    "status": "open"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.BusinessName	string	Nombre de la empresa (para cuentas Business)
data.ID	string	JID completo del dispositivo emparejado
data.Platform	string	Plataforma del dispositivo (`android`, `ios`)
data.jid	string	JID de WhatsApp
data.pushName	string	Nombre de exhibición del perfil
data.status	string	Estado de la conexión (`open`)

Message

Emitido cuando se recibe un mensaje. El payload varía según el tipo de mensaje. Todos los eventos de mensaje comparten la misma estructura base en data, con el objeto Info conteniendo metadatos y Message conteniendo el contenido.

Campos comunes del objeto `Info`

Campo	Tipo	Descripción
Info.Chat	string	JID del chat (individual o grupo)
Info.Sender	string	JID del remitente
Info.SenderAlt	string	JID alternativo del remitente (LID)
Info.IsFromMe	boolean	`true` si el mensaje fue enviado por la propia instancia
Info.IsGroup	boolean	`true` si el mensaje es de un grupo
Info.ID	string	ID único del mensaje
Info.Type	string	Tipo del mensaje (`text`, `media`, etc.)
Info.PushName	string	Nombre de exhibición del remitente
Info.Timestamp	string	Fecha/hora del mensaje (ISO 8601)
Info.MediaType	string	Tipo de media (`image`, `video`, `audio`, `document`)
Info.VerifiedName	object	Información del nombre verificado (cuentas Business)

Campos comunes adicionales

Campo	Tipo	Descripción
IsEphemeral	boolean	Mensaje temporal
IsViewOnce	boolean	Mensaje que puede ser visto solo una vez
IsViewOnceV2	boolean	Mensaje view once v2
IsViewOnceV2Extension	boolean	Extensión view once v2
IsDocumentWithCaption	boolean	Documento con leyenda
IsLottieSticker	boolean	Sticker animado Lottie
IsEdit	boolean	Mensaje editado

Text

{
  "event": "Message",
  "data": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "557499879409:[email protected]",
      "SenderAlt": "123234343434@lid",
      "IsFromMe": false,
      "IsGroup": false,
      "ID": "3EB0C05FF2D3A0068B2A2D",
      "Type": "text",
      "PushName": "Davidson Gomes",
      "Timestamp": "2024-10-10T17:17:44-03:00",
      "MediaType": "",
      "VerifiedName": {
        "Certificate": {
          "details": "CJOzjf3Oh/LGQBIGc21iOndhIg5EYXZpZHNvbiBHb21lcw==",
          "signature": "KjXTl5LfeToLO6bFflbHyiBQe7a1zly4Wdhhf2XPU1Lq8tj9p03hvYUjbs+M0ChWBQhjy/NBq7+nYCKQlLP3Bw=="
        },
        "Details": {
          "serial": 4651594154187643283,
          "issuer": "smb:wa",
          "verifiedName": "Davidson Gomes"
        }
      }
    },
    "Message": {
      "conversation": "oi",
      "messageContextInfo": {
        "deviceListMetadata": {
          "senderKeyHash": "jS2BFebH+KJxzA==",
          "senderTimestamp": 1728407293
        },
        "deviceListMetadataVersion": 2
      }
    },
    "IsEphemeral": false,
    "IsViewOnce": false,
    "IsEdit": false
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Image

Cuando WEBHOOK_FILES=true (predeterminado), el campo base64 contiene la imagen codificada. Si MinIO/S3 está configurado, se agrega mediaUrl en vez de base64.

{
  "event": "Message",
  "data": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "557499879409:[email protected]",
      "IsFromMe": false,
      "IsGroup": false,
      "ID": "3EB0546D154AB4C90A11E1",
      "Type": "media",
      "PushName": "Davidson Gomes",
      "Timestamp": "2024-10-23T09:15:41-03:00",
      "MediaType": "image"
    },
    "Message": {
      "imageMessage": {
        "url": "https://mmg.whatsapp.net/v/...",
        "mimetype": "image/jpeg",
        "fileSha256": "...",
        "fileLength": 82247,
        "height": 1600,
        "width": 1200,
        "mediaKey": "...",
        "fileEncSha256": "...",
        "directPath": "/v/...",
        "mediaKeyTimestamp": 1729685741
      },
      "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..."
    },
    "IsEphemeral": false,
    "IsViewOnce": false,
    "IsEdit": false
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Video

{
  "event": "Message",
  "data": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "557499879409:[email protected]",
      "IsFromMe": false,
      "IsGroup": false,
      "ID": "3EB0A1B2C3D4E5F6071234",
      "Type": "media",
      "PushName": "Davidson Gomes",
      "Timestamp": "2024-10-23T09:20:00-03:00",
      "MediaType": "video"
    },
    "Message": {
      "videoMessage": {
        "url": "https://mmg.whatsapp.net/v/...",
        "mimetype": "video/mp4",
        "fileSha256": "...",
        "fileLength": 1048576,
        "seconds": 15,
        "mediaKey": "...",
        "fileEncSha256": "...",
        "directPath": "/v/...",
        "mediaKeyTimestamp": 1729685741
      },
      "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28y..."
    },
    "IsEphemeral": false,
    "IsViewOnce": false,
    "IsEdit": false
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Audio

{
  "event": "Message",
  "data": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "557499879409:[email protected]",
      "IsFromMe": false,
      "IsGroup": false,
      "ID": "3EB0F1E2D3C4B5A6091234",
      "Type": "media",
      "PushName": "Davidson Gomes",
      "Timestamp": "2024-10-23T09:25:00-03:00",
      "MediaType": "audio"
    },
    "Message": {
      "audioMessage": {
        "url": "https://mmg.whatsapp.net/v/...",
        "mimetype": "audio/ogg; codecs=opus",
        "fileSha256": "...",
        "fileLength": 25600,
        "seconds": 5,
        "ptt": true,
        "mediaKey": "...",
        "fileEncSha256": "...",
        "directPath": "/v/...",
        "mediaKeyTimestamp": 1729685741,
        "waveform": "AAAAAAAAAAAAAAAA..."
      },
      "base64": "T2dnUwACAAAAAAAAAAA..."
    },
    "IsEphemeral": false,
    "IsViewOnce": false,
    "IsEdit": false
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Document

{
  "event": "Message",
  "data": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "557499879409:[email protected]",
      "IsFromMe": false,
      "IsGroup": false,
      "ID": "3EB0D1C2B3A4E5F6071234",
      "Type": "media",
      "PushName": "Davidson Gomes",
      "Timestamp": "2024-10-23T09:30:00-03:00",
      "MediaType": "document"
    },
    "Message": {
      "documentMessage": {
        "url": "https://mmg.whatsapp.net/v/...",
        "mimetype": "application/pdf",
        "title": "documento.pdf",
        "fileSha256": "...",
        "fileLength": 512000,
        "fileName": "documento.pdf",
        "mediaKey": "...",
        "fileEncSha256": "...",
        "directPath": "/v/...",
        "mediaKeyTimestamp": 1729685741
      },
      "base64": "JVBERi0xLjQKJeLj..."
    },
    "IsDocumentWithCaption": false,
    "IsEphemeral": false,
    "IsViewOnce": false,
    "IsEdit": false
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Cuando WEBHOOK_FILES=true (predeterminado), los mensajes con multimedia incluyen el contenido del archivo como base64 dentro del objeto Message. Si MinIO/S3 está configurado, el campo mediaUrl se agrega en vez de base64.

Receipt

Emitido para confirmaciones de lectura y entrega. El campo state en el nivel raíz indica el tipo: Read, ReadSelf o Delivered.

{
  "event": "Receipt",
  "state": "Read",
  "data": {
    "Chat": "[email protected]",
    "Sender": "5511918798714:[email protected]",
    "IsFromMe": false,
    "IsGroup": false,
    "MessageIDs": ["3EB0C05FF2D3A0068B2A2D"],
    "Timestamp": "2024-10-10T17:18:00-03:00",
    "Type": "read"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
state	string	Tipo de confirmación: `Read`, `ReadSelf`, `Delivered`
data.Chat	string	JID del chat
data.Sender	string	JID del remitente
data.MessageIDs	string[]	Lista de IDs de mensajes confirmados
data.Timestamp	string	Fecha/hora de la confirmación (ISO 8601)

Connected

Emitido cuando la instancia se conecta exitosamente a WhatsApp.

{
  "event": "Connected",
  "data": {
    "status": "open",
    "jid": "5511918798714:[email protected]",
    "pushName": "Davidson Gomes"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

LoggedOut

Emitido cuando la instancia se desconecta de WhatsApp.

{
  "event": "LoggedOut",
  "data": {
    "Reason": "logged_out"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

OfflineSyncCompleted

Emitido cuando la sincronización offline de mensajes se completa tras la reconexión.

{
  "event": "OfflineSyncCompleted",
  "data": {
    "Count": 42
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.Count	int	Número de mensajes sincronizados offline

CallOffer

Emitido cuando se recibe una llamada.

{
  "event": "CallOffer",
  "data": {
    "From": "[email protected]",
    "Timestamp": "2024-10-10T17:20:00-03:00",
    "CallCreator": "[email protected]",
    "CallID": "A1B2C3D4E5F6",
    "RemotePlatform": "android",
    "RemoteVersion": "2.24.10.12"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.From	string	JID de quien está llamando
data.Timestamp	string	Fecha/hora de la llamada (ISO 8601)
data.CallCreator	string	JID del creador de la llamada
data.CallID	string	ID único de la llamada
data.RemotePlatform	string	Plataforma del llamador (`android`, `ios`)
data.RemoteVersion	string	Versión del WhatsApp del llamador

CallRelayLatency

Emitido con información de latencia durante una llamada en curso.

{
  "event": "CallRelayLatency",
  "data": {
    "From": "[email protected]",
    "Timestamp": "2024-10-10T17:20:05-03:00",
    "CallCreator": "[email protected]",
    "CallID": "A1B2C3D4E5F6"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

CallTerminate

Emitido cuando una llamada es finalizada.

{
  "event": "CallTerminate",
  "data": {
    "From": "[email protected]",
    "Timestamp": "2024-10-10T17:21:00-03:00",
    "CallCreator": "[email protected]",
    "CallID": "A1B2C3D4E5F6",
    "Reason": "busy"
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.Reason	string	Motivo de la finalización (`busy`, `timeout`, etc.)

JoinedGroup

Emitido cuando la instancia entra en un grupo.

{
  "event": "JoinedGroup",
  "data": {
    "Reason": "invite",
    "JID": "[email protected]",
    "GroupName": {
      "Name": "Equipo Evolution",
      "NameSetAt": "2024-10-01T10:00:00-03:00"
    },
    "GroupCreated": "2024-10-01T10:00:00-03:00",
    "Participants": [
      {
        "JID": "[email protected]",
        "IsAdmin": true,
        "IsSuperAdmin": true
      }
    ]
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.Reason	string	Motivo de la entrada (`invite`, etc.)
data.JID	string	JID del grupo
data.GroupName	object	Informaciones del nombre del grupo
data.Participants	array	Lista de participantes con roles

GroupInfo

Emitido cuando las informaciones de un grupo son actualizadas (nombre, descripción, participantes, etc.).

{
  "event": "GroupInfo",
  "data": {
    "JID": "[email protected]",
    "Sender": "[email protected]",
    "Timestamp": "2024-10-10T17:25:00-03:00",
    "Name": {
      "Name": "Equipo Evolution - Nuevo Nombre",
      "NameSetAt": "2024-10-10T17:25:00-03:00",
      "NameSetBy": "[email protected]"
    },
    "Join": [],
    "Leave": [],
    "Promote": [],
    "Demote": []
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Campo	Tipo	Descripción
data.JID	string	JID del grupo
data.Sender	string	JID de quien hizo el cambio
data.Timestamp	string	Fecha/hora del cambio (ISO 8601)
data.Name	object	Nuevo nombre del grupo (si fue cambiado)
data.Topic	object	Nueva descripción del grupo (si fue cambiada)
data.Join	array	JIDs de usuarios que entraron al grupo
data.Leave	array	JIDs de usuarios que salieron del grupo
data.Promote	array	JIDs de usuarios promovidos a admin
data.Demote	array	JIDs de usuarios degradados de admin

NewsletterJoin

Emitido cuando la instancia entra en un canal/newsletter.

{
  "event": "NewsletterJoin",
  "data": {
    "id": "120363123456789012@newsletter",
    "state": {
      "type": "ACTIVE"
    },
    "thread_metadata": {
      "creation_time": "1696118400",
      "invite": "ABC123DEF456",
      "name": {
        "text": "Evolution Go News",
        "id": "1234567890"
      },
      "description": {
        "text": "Canal oficial de Evolution Go"
      },
      "subscribers_count": 1500,
      "verification": "VERIFIED",
      "picture": {
        "url": "https://pps.whatsapp.net/v/..."
      }
    },
    "viewer_metadata": {
      "mute": "OFF",
      "role": "SUBSCRIBER"
    }
  },
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062"
}

Política de Reintentos

Evolution Go posee un sistema automático de reintentos para garantizar la entrega de los webhooks:

Configuración	Valor
Máximo de intentos	5
Intervalo entre intentos	30 segundos
Método HTTP	`POST`
Content-Type	`application/json`
Respuesta esperada	Estado HTTP `2xx`

Si los 5 intentos fallan, el evento se descarta y se registra un log de error.

Asegúrese de que su endpoint de webhook responda con estado HTTP 2xx (200-299) para confirmar la recepción. Cualquier respuesta fuera de ese rango será tratada como fallo y activará un nuevo intento.

Canales de Entrega Alternativos

Además de webhooks HTTP, Evolution Go soporta otros canales de entrega de eventos:

RabbitMQ / AMQP

Envío via colas AMQP. Configure con rabbitmqEnable: "enabled" en la conexión de la instancia y las variables AMQP_URL, AMQP_GLOBAL_ENABLED y AMQP_GLOBAL_EVENTS.

NATS

Envío via NATS messaging. Configure con natsEnable: "enabled" en la conexión y las variables NATS_URL, NATS_GLOBAL_ENABLED y NATS_GLOBAL_EVENTS.

WebSocket

Reciba eventos en tiempo real via WebSocket. Configure con websocketEnable: "enabled" en la conexión de la instancia.

Múltiples canales pueden activarse simultáneamente. Por ejemplo, puede recibir eventos via webhook HTTP y RabbitMQ al mismo tiempo.

Variables de Entorno

Todas las variables de entorno relacionadas con eventos y webhooks:

Variable	Descripción	Predeterminado
`WEBHOOK_URL`	URL del webhook global	-
`WEBHOOK_FILES`	Incluir archivos multimedia en payloads	`true`
`AMQP_URL`	URL de conexión de RabbitMQ	-
`AMQP_GLOBAL_ENABLED`	Activar colas globales RabbitMQ	`false`
`AMQP_GLOBAL_EVENTS`	Eventos para colas globales (separados por coma)	-
`AMQP_SPECIFIC_EVENTS`	Eventos para colas específicas (separados por coma)	-
`NATS_URL`	URL de conexión de NATS	-
`NATS_GLOBAL_ENABLED`	Activar NATS global	`false`
`NATS_GLOBAL_EVENTS`	Eventos para NATS global (separados por coma)	-
`EVENT_IGNORE_GROUP`	Ignorar eventos de grupos	`false`
`EVENT_IGNORE_STATUS`	Ignorar eventos de estado/stories	`false`

​Guía Rápida

​Prerrequisitos

​Paso 1: Conectar la instancia con webhook

​Método

​Header

​Body

​Ejemplo con cURL

​Ejemplo con JavaScript

​Ejemplo con Python

​Paso 2: Emparejar con WhatsApp

​Paso 3: Confirmar la conexión

​Paso 4: Recibir mensajes

​Procesando en su servidor

​Configuración Detallada

​Webhook por Instancia

​Parámetros

​Webhook Global

​Tipos de Eventos

​Estructura del Payload

​Payloads por Evento

​QRCode

​PairSuccess

​Message

​Campos comunes del objeto Info

​Campos comunes adicionales

​Text

​Image

​Video

​Audio

​Document

​Receipt

​Connected

​LoggedOut

​OfflineSyncCompleted

​CallOffer

​CallRelayLatency

​CallTerminate

​JoinedGroup

​GroupInfo

​NewsletterJoin

​Política de Reintentos

​Canales de Entrega Alternativos

RabbitMQ / AMQP

NATS

WebSocket

​Variables de Entorno

Guía Rápida

Prerrequisitos

Paso 1: Conectar la instancia con webhook

Método

Header

Body

Ejemplo con cURL

Ejemplo con JavaScript

Ejemplo con Python

Paso 2: Emparejar con WhatsApp

Paso 3: Confirmar la conexión

Paso 4: Recibir mensajes

Procesando en su servidor

Configuración Detallada

Webhook por Instancia

Parámetros

Webhook Global

Tipos de Eventos

Estructura del Payload

Payloads por Evento

QRCode

PairSuccess

Message

Campos comunes del objeto `Info`

Campos comunes adicionales

Text

Image

Video

Audio

Document

Receipt

Connected

LoggedOut

OfflineSyncCompleted

CallOffer

CallRelayLatency

CallTerminate

JoinedGroup

GroupInfo

NewsletterJoin

Política de Reintentos

Canales de Entrega Alternativos

Variables de Entorno