Webhook de la Instancia

Gestione la configuración para recibir notificaciones de mensajes, conexiones y otros eventos en tiempo real en su servidor.

Herramientas de Prueba

Antes de integrar, recomendamos probar la recepción de los datos. Utilice una de estas herramientas para inspeccionar el payload:

Webhook.cool

Recomendado. Sin rate limit y con una interfaz muy limpia.

SVIX

Buena alternativa. Confiable y con un rate limit bajo.

Webhook.site

Evítelo si es posible. Tiene rate limits muy agresivos.

Modo Simple (Recomendado)

Esta es la forma más fácil de configurarlo. El sistema gestiona automáticamente un único webhook por instancia, creándolo o actualizándolo según sea necesario. Reglas:

No incluya action ni id en el payload.
Use siempre filtros para evitar bucles infinitos.

Prevención de BuclesSi utiliza automatizaciones, incluya siempre "excludeMessages": ["wasSentByApi"]. Esto impide que los mensajes enviados por su propio bot disparen nuevos eventos y generen un bucle infinito.

Ejemplo de Payload

{
  "url": "[https://meusite.com/webhook](https://meusite.com/webhook)",
  "events": [
    "messages",
    "connection"
  ],
  "excludeMessages": [
    "wasSentByApi"
  ]
}

Modo Avanzado

Utilice este modo solo si necesita registrar múltiples webhooks para la misma instancia (ej.: un webhook para mensajes y otro para el estado de conexión).

Consejo Pro: Aunque necesite múltiples endpoints, considere usar la función de Parámetros de URL (vea el final de la página) con el Modo Simple. Es más fácil de mantener.

Gestión Manual

Para controlar múltiples webhooks, debe enviar el campo action.

{
  "action": "add",
  "url": "[https://api.site.com/webhook-1](https://api.site.com/webhook-1)",
  "events": ["messages"]
  // O sistema gera um ID automaticamente
}

{
  "action": "update",
  "id": "ID_DO_WEBHOOK", // Obrigatório
  "url": "[https://api.site.com/nova-url](https://api.site.com/nova-url)",
  "events": ["messages", "call"]
}

{
  "action": "delete",
  "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário
}

Eventos Disponibles

Seleccione qué tipos de notificación desea recibir en el array events.

Mensajes y Conversaciones

Evento	Descripción
`messages`	Nuevos mensajes recibidos.
`messages_update`	Actualización de estado (entregado, leído) o edición.
`history`	Recepción del historial de mensajes al conectarse.
`chats`	Eventos relacionados con la lista de conversaciones.
`chat_labels`	Cambios en las etiquetas de las conversaciones.

Sistema y Conexión

Evento	Descripción
`connection`	Cambios de estado (Código QR, Conectado, Desconectado).
`presence`	Cambios en el estado de presencia (en línea, escribiendo).
`contacts`	Actualizaciones en la agenda de contactos.
`groups`	Modificaciones en grupos (título, participantes).
`blocks`	Bloqueos y desbloqueos de contactos.
`call`	Eventos de llamadas de voz/video.

Marketing y Leads

Evento	Descripción
`leads`	Actualizaciones de leads.
`labels`	Gestión de etiquetas.
`sender`	Actualizaciones de campañas (inicio/fin).

Filtros de Exclusión (`excludeMessages`)

Use el campo excludeMessages para ignorar mensajes específicos y ahorrar procesamiento.

Filtro	Descripción
`wasSentByApi`	Importante: Ignora los mensajes enviados por la propia API.
`wasNotSentByApi`	Ignora los mensajes que NO fueron enviados por la API.
`fromMeYes`	Ignora los mensajes enviados por el propio usuario (celular).
`fromMeNo`	Ignora los mensajes recibidos de otras personas.
`isGroupYes`	Ignora los mensajes provenientes de grupos.
`isGroupNo`	Ignora los mensajes de conversaciones privadas.

Parámetros de URL (Rutas Dinámicas)

Puede hacer que la API agregue información directamente en la URL de su webhook, lo que facilita el enrutamiento en su backend (ej.: usando Node.js/Express o Laravel Routes).

Opciones Disponibles

addUrlEvents

Agrega el evento a la URL. .../webhook/{evento}

addUrlTypesMessages

Agrega el tipo de mensaje a la URL. .../webhook/{tipo}

Ejemplos de Resultados

Suponga que su URL base es https://api.example.com/webhook:

Solo Eventos (addUrlEvents: true):
- https://api.example.com/webhook/message
- https://api.example.com/webhook/connection
Solo Tipos (addUrlTypesMessages: true):
- https://api.example.com/webhook/conversation (texto)
- https://api.example.com/webhook/image (multimedia)
Ambos Activos (Combinación): El orden es siempre: {URL_BASE}/{EVENTO}/{TIPO_MENSAGEM}
- https://api.example.com/webhook/message/conversation
- https://api.example.com/webhook/message/audio

Asegúrese de que su backend esté configurado para aceptar parámetros dinámicos (wildcards) en la ruta para procesar estas URLs correctamente.

Primeros Pasos

Configurar Webhook

Webhook de la Instancia

Herramientas de Prueba

Webhook.cool

SVIX

Webhook.site

Modo Simple (Recomendado)

Ejemplo de Payload

Modo Avanzado

Gestión Manual

Eventos Disponibles

Filtros de Exclusión (`excludeMessages`)

Parámetros de URL (Rutas Dinámicas)

Opciones Disponibles

addUrlEvents

addUrlTypesMessages

Ejemplos de Resultados

​Webhook de la Instancia

​ Herramientas de Prueba

Webhook.cool

SVIX

Webhook.site

​ Modo Simple (Recomendado)

​Ejemplo de Payload

​ Modo Avanzado

​Gestión Manual

​Eventos Disponibles

​Filtros de Exclusión (excludeMessages)

​Parámetros de URL (Rutas Dinámicas)

​Opciones Disponibles

addUrlEvents

addUrlTypesMessages

​Ejemplos de Resultados

Webhook de la Instancia

Herramientas de Prueba

Modo Simple (Recomendado)

Ejemplo de Payload

Modo Avanzado

Gestión Manual

Eventos Disponibles

Filtros de Exclusión (`excludeMessages`)

Parámetros de URL (Rutas Dinámicas)

Opciones Disponibles

Ejemplos de Resultados