> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurar Webhook

> Reciba eventos en tiempo real de su instancia mediante Webhook.

# Webhook de la Instancia

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

## <Icon icon="flask" size={22} /> Herramientas de Prueba

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

<CardGroup cols={3}>
  <Card href="https://webhook.cool/" title="Webhook.cool">
    <img src="https://icons.duckduckgo.com/ip3/webhook.cool.ico" width="40" className="mb-4" />

    **Recomendado.** Sin rate limit y con una interfaz muy limpia.
  </Card>

  <Card href="https://svix.com/play" title="SVIX">
    <img src="https://icons.duckduckgo.com/ip3/svix.com.ico" width="40" className="mb-4" />

    Buena alternativa. Confiable y con un rate limit bajo.
  </Card>

  <Card href="https://webhook.site/" title="Webhook.site">
    <img src="https://icons.duckduckgo.com/ip3/webhook.site.ico" width="40" className="mb-4" />

    Evítelo si es posible. Tiene rate limits muy agresivos.
  </Card>
</CardGroup>

***

## <Icon icon="rocket" size={22} /> 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:**

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

<Warning>
  **Prevención de Bucles**

  Si utiliza automatizaciones, incluya **siempre** `"excludeMessages": ["wasSentByApi"]`. Esto impide que los mensajes enviados por su propio bot disparen nuevos eventos y generen un bucle infinito.
</Warning>

### Ejemplo de Payload

```json theme={null}
{
  "url": "https://meusite.com/webhook",
  "events": [
    "messages",
    "connection"
  ],
  "excludeMessages": [
    "wasSentByApi"
  ]
}
```

***

## <Icon icon="gear" size={22} /> 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).

<Tip>
  **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.
</Tip>

### Gestión Manual

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

<CodeGroup>
  ```json Crear (Add) theme={null}
  {
    "action": "add",
    "url": "https://api.site.com/webhook-1",
    "events": ["messages"]
    // O sistema gera um ID automaticamente
  }
  ```

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

  ```json Eliminar (Delete) theme={null}
  {
    "action": "delete",
    "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário
  }
  ```
</CodeGroup>

***

## Eventos Disponibles

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

<AccordionGroup>
  <Accordion title="Mensajes y Conversaciones" icon="message">
    | 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. |
  </Accordion>

  <Accordion title="Sistema y Conexión" icon="server">
    | 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. |
  </Accordion>

  <Accordion title="Marketing y Leads" icon="bullhorn">
    | Evento | Descripción |
    | :- | :- |
    | `leads` | Actualizaciones de leads. |
    | `labels` | Gestión de etiquetas. |
    | `sender` | Actualizaciones de campañas (inicio/fin). |
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="addUrlEvents" icon="bolt">
    Agrega el **evento** a la URL.
    `.../webhook/{evento}`
  </Card>

  <Card title="addUrlTypesMessages" icon="envelope-open-text">
    Agrega el **tipo de mensaje** a la URL.
    `.../webhook/{tipo}`
  </Card>
</CardGroup>

### Ejemplos de Resultados

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

1. **Solo Eventos (`addUrlEvents: true`):**
   * `https://api.example.com/webhook/message`
   * `https://api.example.com/webhook/connection`

2. **Solo Tipos (`addUrlTypesMessages: true`):**
   * `https://api.example.com/webhook/conversation` (texto)
   * `https://api.example.com/webhook/image` (multimedia)

3. **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`

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.