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

# Webhooks

> Recibir eventos de WhatsApp como peticiones HTTP POST firmadas: configuración, tipos de eventos, formato de carga útil, firmas y reintentos.

GOWA POSTs un documento JSON a tu URL para cada evento WhatsApp que recibe: mensajes, recibos, reacciones, ediciones, eliminaciones, indicadores de tecleo, cambios de grupo, etiquetas, boletines y llamadas.

No hay ningún punto final de registro de webhook. Configurar webhooks al inicio, o por dispositivo a través de `/devices/{device_id}/webhook`.

## Cómo funciona el envío

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant WA as WhatsApp
    participant G as GOWA
    participant R as Your receiver
    WA->>G: Event (whatsmeow)
    G->>G: Skip if chat/sender matches WHATSAPP_WEBHOOK_IGNORE_JIDS
    G->>G: Resolve targets (per-device webhook or global WHATSAPP_WEBHOOK)
    G->>G: Skip target if event not in its allowlist (WHATSAPP_WEBHOOK_EVENTS)
    loop Up to 5 attempts, 10 s timeout each
        G->>R: POST JSON {event, device_id, session_id, payload}<br/>X-Hub-Signature-256: sha256=HMAC(body, secret)
        R->>R: Verify HMAC over raw body
        alt 2xx
            R-->>G: 200 OK (delivered, stop)
        else non-2xx or network error
            R-->>G: Error
            G->>G: Wait 1 s, 2 s, 4 s, then 8 s before the next attempt
        end
    end
    Note over G: After the 5th failure the event is logged and dropped
```

Cada URL de destino se entrega de forma independiente, con su propio secreto y reintentos.

## Configurar

```bash theme={null}
# one or more URLs, comma-separated
WHATSAPP_WEBHOOK=https://example.com/wa-hook,https://backup.example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=replace-with-a-private-key # stable HMAC key
WHATSAPP_WEBHOOK_EVENTS=message,message.ack # optional allowlist; empty = all events
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us          # optional; skip chats or senders
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=false # verify HTTPS certificates
WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=false  # optional linked-device receipts
```

Banderas equivalentes: `--webhook`, `--webhook-secret`, `--webhook-events`, `--webhook-ignore-jids`, `--webhook-insecure-skip-verify`, y `--webhook-all-device-receipts`.

Establece explícitamente una clave de firma privada. Si no se configura ninguna clave o se usa el antiguo valor publicado `secret`, GOWA genera una clave aleatoria que cambia al reiniciar y registra una advertencia. Los receptores necesitan una clave compartida explícita para verificar las firmas tras los reinicios. Los certificados HTTPS se verifican de forma predeterminada.

## Eventos

| Evento | Disparado cuando |
| - | - |
| `message` | Un mensaje llega (texto, medios, contacto, ubicación, encuesta, etc.). `is_from_me` es `true` para los mensajes enviados por esta cuenta. |
| `message.reaction` | Alguien reacciona a un mensaje. |
| `message.revoked` | Un mensaje es eliminado para todos. |
| `message.edited` | Se ha editado un mensaje. |
| `message.ack` | Entrega o lee el recibo (`receipt_type`: `delivered`, `read`, ...). |
| `message.deleted` | Un mensaje es eliminado para usted solamente. |
| `chat_presence` | Un contacto comienza o deja de escribir o grabar. |
| `presence` | Un contacto suscrito se conecta o desconecta. Requiere una suscripción de presencia y un cliente disponible. |
| `group.participants` | Los miembros se unen, abandonan, son promovidos o degradados (`type`: `join`, `leave`, `promote`, `demote`). |
| `group.info` | Un nombre de grupo cambia. Payload incluye el nuevo `name` y, cuando se conoce, `name_set_by`. |
| `group.joined` | Tu cuenta ha sido añadida a un grupo. |
| `label.edit` | Una etiqueta de negocios de WhatsApp es creada o cambiada. |
| `label.association` | Una etiqueta es aplicada o eliminada de un chat. |
| `newsletter.joined` / `newsletter.left` | Seguir o dejar de seguir un canal. |
| `newsletter.message` | Actualizaciones del contador de reacción y vista en vivo para los mensajes suscritos al canal. |
| `newsletter.mute` | Cambia la configuración de silencio de un canal. |
| `call.offer` | Llamada entrante. Con `WHATSAPP_AUTO_REJECT_CALL=true` es rechazado automáticamente. |
| `device.logged_out` | WhatsApp cierra la sesión del dispositivo, incluyendo su código de motivo. |
| `device.temporary_ban` | WhatsApp prohíbe temporalmente la cuenta. |
| `device.reachout_timelock` | WhatsApp activa o levanta una restricción para iniciar nuevas conversaciones. |

Los nombres de eventos en la lista permitida son insensibles mayúsculas y minúsculas.

## Carga útil

Cada solicitud tiene el mismo sobre:

```json theme={null}
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "payload": {
    "id": "3EB0C127D7BACC83D6A1",
    "chat_id": "628987654321@s.whatsapp.net",
    "from": "628987654321@s.whatsapp.net",
    "from_lid": "251556368777322@lid",
    "from_name": "John Doe",
    "sender_display_name": "John Doe",
    "timestamp": "2026-10-15T10:30:00Z",
    "is_from_me": false,
    "body": "Hello, how are you?"
  }
}
```

| Campo | Descripción |
| - | - |
| `event` | Uno de los nombres de los eventos anteriores. |
| `device_id` | JID de la cuenta que recibió el evento. Los eventos del dispositivo lo omiten si la ranura no tiene JID todavía. |
| `session_id` | ID de la ranura, como el ID de `POST /devices`. Las ranuras creadas automáticamente pueden usar un JID de WhatsApp. Los eventos del dispositivo siempre lo incluyen. Otros eventos pueden omitirlo si el JID no puede ser mapeado a una ranura. |
| `payload` | Datos específicos del evento. Campos comunes: `id`, `chat_id`, `from`, `from_lid`, `from_name`, `sender_display_name`, `timestamp` (RFC 3339), `is_from_me`. |

Las respuestas añaden `replied_to_id` y `quoted_body`. Los recibos usan `ids` (array) y `receipt_type`. Agrupa eventos participantes llevan `chat_id`, `type`, y `jids`. Los cambios de nombre de grupo usan una forma separada `group.info`.

`sender_display_name` aparece sólo cuando `from` es una cadena no vacía. Para otro remitente, GOWA prefiere el nombre de contacto guardado, el nombre de envío en vivo del evento, el nombre de la empresa, y la parte de usuario de JID. Para la cuenta activa, prefiere el nombre push de la cuenta, luego su identidad JID. La resolución es el mejor esfuerzo. El legado `from_name` sigue siendo el mensaje evento push name.

Los mensajes entrantes pueden incluir `is_business: true`, `verified_name` y `verified_level` cuando WhatsApp proporciona un certificado de nombre verificado. En caso contrario, estos campos se omiten. Su ausencia no permite determinar si el remitente es una empresa, y `verified_level` es el valor sin procesar proporcionado por WhatsApp, no una garantía de una insignia oficial.

### Medios

Con `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (por defecto), los medios se guardan en `statics/media/` y el campo multimedia guarda la ruta:

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

Cuando hay un pie de foto, el campo pasa a ser `{"path": "...", "caption": "..."}` y el pie de foto también aparece en `body`. Con la descarga automática desactivada, es `{"url": "https://mmg.whatsapp.net/...", "caption": "..."}`; descarga el archivo más tarde con `GET /message/{message_id}/download?phone=<chat>`.

El catálogo completo de payloads (encuestas, ubicaciones, contactos, vista-una vez, referencias de anuncios y más) está en la línea de desarrollo principal [referencia de payhook webhook](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/webhook-payload.md).

## Álbumes y mensajes estructurados

Un álbum llega como varios eventos `message`. La cabecera no tiene cuerpo de mensaje e incluye los recuentos de elementos esperados:

```json theme={null}
{
  "id": "ALBUM_HEADER_ID",
  "album": {
    "expected_image_count": 3,
    "expected_video_count": 1
  }
}
```

Cada foto o video llega en su propio evento mediático normal con `album_id: "ALBUM_HEADER_ID"`. Agrupa elementos con ese ID. El encabezado no es un elemento multimedia descargable y no se remite a Chatwoot.

Creación de encuestas, votos, ediciones y opciones añadidas también usan `message`. Inspecciona el objeto estructurado `poll` en lugar de depender de `body`. Los hasks de opción son hexadecimales en minúsculas SHA-256 con nombres de opción exactos. Las suscripciones existentes `WHATSAPP_WEBHOOK_EVENTS=message` reciben estas interacciones.

## Presencia en línea y fuera de línea

Suscríbete para cada contacto individual utilizando el mismo dispositivo que recibe los eventos:

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/user/presence/subscribe \
  -H "X-Device-Id: sales" \
  -H "Content-Type: application/json" \
  -d '{"phone":"628987654321"}'
```

Una respuesta exitosa contiene `results.subscribed: true` y `results.jid`. Grupo y boletines JIDs son rechazados. Una suscripción no anula la configuración de presencia de tu dispositivo. Para actualizaciones continuas, inicia GOWA con:

```bash theme={null}
WHATSAPP_PRESENCE_ON_CONNECT=available
WHATSAPP_PRESENCE_PULSE_ENABLED=false
WHATSAPP_WEBHOOK_EVENTS=message,presence
```

El pulso de presencia por defecto termina marcando el dispositivo no disponible, lo que detiene las actualizaciones de presencia de contactos. Marcar el dispositivo disponible suprime las notificaciones push de WhatsApp en el teléfono mientras se ejecuta. Cuenta para esta operación antes de habilitar el seguimiento continuo.

```json theme={null}
{
  "event": "presence",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:05:00Z",
  "payload": {
    "from": "628987654321@s.whatsapp.net",
    "state": "unavailable",
    "last_seen": "2026-10-29T12:04:35Z"
  }
}
```

`state` es `available` o `unavailable`. `last_seen` se omite cuando se desconoce u se oculta en la configuración de privacidad del contacto. `from_lid` se incluye cuando corresponda. Typing y grabación permanecen separados eventos `chat_presence` y no usen esta suscripción.

## Cambios de nombre de grupo

```json theme={null}
{
  "event": "group.info",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T10:35:00Z",
  "payload": {
    "chat_id": "120363402106000000@g.us",
    "name": "Project team",
    "name_set_by": "628987654321@s.whatsapp.net"
  }
}
```

`name_set_by` se resuelve de LID al JID del teléfono cuando es posible y se omite cuando WhatsApp no identifica al actor. Suscríbete a `group.info` explícitamente si tu lista de eventos excluye otros eventos.

## Actualizaciones del boletín

`newsletter.message` reporta contadores en vivo en lugar de un nuevo mensaje garantizado. Las entradas siempre incluyen `server_id`. `message_id`, `type`, y `timestamp` son omitidos cuando WhatsApp no los suministra. Pueden omitirse contadores cero o ausentes.

```json theme={null}
{
  "event": "newsletter.message",
  "device_id": "628123456789@s.whatsapp.net",
  "timestamp": "2026-10-29T12:00:00Z",
  "payload": {
    "newsletter_id": "120363000000000000@newsletter",
    "messages": [
      {"server_id": 42, "views_count": 120, "forwards_count": 3}
    ]
  }
}
```

Cuando esté disponible, `reaction_counts` contiene el recuento de reacción de WhatsApp. Consume actualizaciones por ID del boletín de noticias e ID del servidor. No trate un contador que falte como un restablecimiento a cero.

## Restricciones de la cuenta y cierre de sesión

Los eventos del dispositivo siempre llevan `session_id`, así que las ranuras usando el mismo número de WhatsApp siguen siendo distinguibles. El evento utiliza la configuración del webhook de la zona de emisión. Un cierre de sesión remoto mantiene la ranura para volver a emparejar e informa de la identidad de antes de salir. Los ajustes de webhook de la ranura sobreviven a la revinculación. Estos eventos no se envían a Chatwoot.

```json theme={null}
{
  "event": "device.logged_out",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "sales",
  "timestamp": "2026-10-29T09:00:00Z",
  "payload": {
    "code": 401,
    "reason": "logged out from another device",
    "on_connect": true
  }
}
```

| Evento | Campos de carga útil |
| - | - |
| `device.logged_out` | `code`, `reason`, `on_connect`. `on_connect` distingue una conexión rechazada de una conexión abierta que se está cerrando. |
| `device.temporary_ban` | `code`, `reason`, `expires_in_seconds`. `expires_at` es un RFC 3339 calculado y aparece sólo cuando la duración es positiva. La sesión es entera. |
| `device.reachout_timelock` | `is_active`. Opcional `enforcement_type` pasa a través del valor de WhatsApp. El `ends_at` opcional es un expiración RFC 333339. `is_active: false` significa WhatsApp levantó la restricción. |

Los códigos son enviados sin cambios y la razón de que el texto viene de lo que quiera. Los códigos desconocidos todavía llegan. Los códigos de salida `403` y `406` solos no establecen la causa exacta. Una duración temporal de bloqueo de cero significa que WhatsApp no ha expirado. Un bloqueo de tiempo de alcance restringe el inicio de nuevos chats y puede producir el error de envío 463.

## Verificar firmas

Cada solicitud lleva `X-Hub-Signature-256: sha256=<hex>`, un cuerpo HMAC-SHA256 de la solicitud **cruda** clavado con el secreto del webhook. Calcular sobre los bytes exactos recibidos, antes de analizar JSON.

```javascript Node.js (Express) theme={null}
const express = require("express");
const crypto = require("crypto");
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;

app.post("/wa-hook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const signature = req.get("X-Hub-Signature-256") || "";
  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return res.sendStatus(401);
  const received = signature.slice(7);
  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.sendStatus(401);
  }
  const evt = JSON.parse(req.body);
  res.sendStatus(200);            // acknowledge fast
  handle(evt);                    // then process
});
```

```python Python (Flask) theme={null}
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"].encode()

@app.post("/wa-hook")
def wa_hook():
    raw = request.get_data()
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Hub-Signature-256", "").removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        abort(401)
    evt = request.get_json()
    # enqueue evt for processing
    return "", 200
```

```go Go theme={null}
func waHook(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	mac := hmac.New(sha256.New, []byte(os.Getenv("WEBHOOK_SECRET")))
	mac.Write(raw)
	expected := hex.EncodeToString(mac.Sum(nil))
	received := strings.TrimPrefix(r.Header.Get("X-Hub-Signature-256"), "sha256=")
	if !hmac.Equal([]byte(expected), []byte(received)) {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK)
	// process raw asynchronously
}
```

## Entrega y reintentos

* Cada intento expira después de **10 segundos**.
* Cualquier respuesta que no sea 2xx o error de red es recuperada. GOWA compone hasta **5 intentos**, esperando 1 s, 2 s, 4 y 8 s entre ellos. La fecha límite del contexto del gestor de eventos puede detener la entrega antes de que se completen todos los intentos.
* Después del último fallo el evento es eliminado y registrado. No hay cola persistente ni almacén de letras muertas.
* Varias URLs se entregan de forma independiente.

Responde `2xx` después de aceptar el evento en su propia cola de procesamiento duradera. Hace que los manejadores sean idempotentes porque un evento reprobado puede llegar más de una vez.

## Recibos de dispositivos conectados

De forma predeterminada, GOWA reenvía los reconocimientos de contacto desde dispositivos primarios sólo para reducir duplicados. Los recibos de la cuenta corriente `read` y `read-self` pasan de todos sus dispositivos. Para estos recibos de propia cuenta, `payload.from` es el JID de la cuenta y `payload.ids` identifica los mensajes entrantes que fueron leídos.

Establece `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true` o `--webhook-all-device-receipts=true` para recibir también las confirmaciones de los contactos desde los dispositivos vinculados, incluso cuando el teléfono del contacto esté desconectado. La opción de la CLI prevalece sobre la variable de entorno, incluido un valor explícito `false`.

Esta opción puede producir reconocimientos duplicados o fuera de orden. Aplicar actualizaciones idempotentemente por cuenta, chat e ID del mensaje. Nunca reduzca un mensaje de lectura para entregarlo cuando llegue un recibo antiguo. Los IDs de mensajes y los JIDs de remitente mantienen su forma canónica sin sufijos de dispositivos.

## Filtrar eventos

**Por tipo:** `WHATSAPP_WEBHOOK_EVENTS=message,message.ack` reenvía sólo esos eventos.

**Por chat o enviador:** `WHATSAPP_WEBHOOK_IGNORE_JIDS` coincide con `chat_id`, `from`, `chat_lid` y `from_lid`. Las entradas que empiezan con `@` son comodines para un espacio de direcciones completo (`@g.us`, `@s.whatsapp.net`, `@lid`); cualquier otra cosa es un JIG exacto.

```bash theme={null}
# drop all group traffic plus one specific contact
WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us,628123456789@s.whatsapp.net
```

`@s.whatsapp.net` también coincide con los mensajes de grupo, porque su `from` es un usuario JID. Usa `@g.us` para silenciar grupos. Los dos filtros combinados: un evento se envía sólo si su tipo está permitido **y** su JID no es ignorado.

## Webhooks por dispositivo

Dar a una ranura su propio webhook, secreto y lista de eventos permitidos:

```bash theme={null}
curl -u admin:changeme -X PATCH http://localhost:3000/devices/sales/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://sales.example.com/wa-hook",
    "webhook_secret": "sales-secret",
    "webhook_events": "message,message.ack",
    "webhook_insecure_skip_verify": false
  }'
```

Los mismos campos son aceptados por `POST /devices`. Lee la configuración actual con `GET /devices/{device_id}/webhook`. Send `"webhook_url": ""` para borrarlo.

Un dispositivo vacío `webhook_secret` o `webhook_events` vuelve a la configuración global correspondiente. El dispositivo almacenado `webhook_insecure_skip_verify` boolean reemplaza la configuración global de TLS. En particular, `false` mantiene habilitada la verificación de certificados incluso cuando el bypass global está habilitado.

```mermaid theme={null}
flowchart TD
    A[Event for a device] --> B{Device has its own webhook_url?}
    B -- No --> G[Send to global WHATSAPP_WEBHOOK URLs<br/>global secret and allowlist]
    B -- Yes --> C{WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true?}
    C -- No --> D[Send to device URL only<br/>device secret and allowlist]
    C -- Yes --> E[Send to device URL and global URLs<br/>each with its own secret and allowlist<br/>duplicate URLs receive the event once]
```

Por defecto una URL por dispositivo **reemplaza** el `WHATSAPP_WEBHOOK` global para esa ranura. Con `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true` se **agrega** a las URL globales en su lugar: la URL del dispositivo utiliza el secreto y lista permitida, las URLs globales mantienen las globales, y una URL presente en ambas recibe el evento una vez. Las reglas Ignore-JID se aplican a ambos.

## Probando localmente

Exponga un receptor local con un túnel (por ejemplo `ngrok http 8080`) y establezca `WHATSAPP_WEBHOOK` en la URL del túnel. Con `--debug=true`, GOWA registra cada intento de entrega y fallo.

## Otras formas de recibir eventos

* **[WebSocket](https://gowa-docs.mintlify.site/es/api-reference/websocket.md)** en `/ws?device_id=<id>` empuja los eventos de emparejamiento y estado con los clientes del panel de control. Usa webhooks para la entrega de mensajes.
* **Polling:** `GET /chats` y `GET /chat/{chat_jid}/messages` leen el almacenamiento local de chat de GOWA. Vea [Recibiendo mensajes](https://gowa-docs.mintlify.site/es/examples/receiving-messages.md).


## Related topics

- [Establecer configuración del dispositivo webhook](https://gowa-docs.mintlify.site/es/api-reference/device/establecer-configuración-del-dispositivo-webhook.md)
- [Final de webhook de Chatwoot](https://gowa-docs.mintlify.site/es/api-reference/chatwoot/final-de-webhook-de-chatwoot.md)
- [Obtener configuración de webhook del dispositivo](https://gowa-docs.mintlify.site/es/api-reference/device/obtener-configuración-de-webhook-del-dispositivo.md)
- [Referencia de configuración](https://gowa-docs.mintlify.site/es/configuration.md)
- [Recibiendo mensajes](https://gowa-docs.mintlify.site/es/examples/receiving-messages.md)


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