# Los 9 tipos de evento con su payload

8 tipos **suscribibles** + `webhook.test` (no suscribible). Un endpoint con lista de `events` explícita recibe SOLO esos tipos; lista vacía/omitida = todos (los nuevos entran solos). El `data` de cada uno:

| Tipo | Suscribible | Descripción |

| --- | --- | --- |

| `message.received` | ✓ | Un cliente te escribió. data.message = objeto de mensaje de WhatsApp (texto/imagen/audio/…); data.contacts[] identifica al remitente. |

| `message.echo` | ✓ | 🌟 Diferencial de Coexistence: un mensaje que el DUEÑO envió DESDE EL TELÉFONO, con su contenido. origin='device' (no consume el plan). from = tu número de negocio. |

| `message.status` | ✓ | Acuse de un mensaje que enviaste por /v1. origin (api\|device) distingue tu envío del envío hecho a mano desde el teléfono. Un acuse 'device' NO tiene mensaje tuyo detrás — es esperado. |

| `connection.created` | ✓ | Se conectó un número nuevo (panel u onboarding hospedado). Tu externalId viaja en el sobre → provisioná al cliente final en tu sistema. |

| `connection.status_changed` | ✓ | Cambió el estado de una conexión (ej. status='disconnected'). Alertá o pausá los envíos a ese número. |

| `connection.usage_threshold_reached` | ✓ | El límite de UN número (su monthlyMessageLimit) llegó a 70/90/100%. Se emite UNA vez por (número, período, umbral). El comercial: avisale a ese cliente final o subile el tope. |

| `usage.threshold_reached` | ✓ | El plan de la CUENTA (suma de todos los números) llegó a un umbral. connection viene en null, sequence 0. Decidí upgrade o corte. |

| `history.synced` | ✓ | (Coexistence) resumen del backfill de conversaciones al conectar. shared:false = el dueño no compartió su historial. ⚠ Los mensajes históricos NO se reenvían uno por uno. |

| `subscription.activated` | ✓ | (Facturación) el primer pago se confirmó y la cuenta del cliente del reseller pasó a activa. connection=null. Reaccioná activando su servicio. |

| `subscription.cancelled` | ✓ | (Facturación) baja de la suscripción. Sigue funcionando hasta accessUntil; después bloquea el envío (no la recepción). connection=null. |

| `billing.payment_failed` | ✓ | (Facturación) un cobro recurrente falló. Entra en aviso/gracia (no corta nada todavía). Duneá a tu cliente ANTES del corte. connection=null. |

| `billing.payment_recovered` | ✓ | (Facturación) el pago se regularizó y la cuenta se reactivó sola. connection=null. |

| `billing.amount_updated` | ✓ | (Facturación) cambió el importe de tu próxima renovación. Podés mostrarle el importe a tu cliente antes de que se cobre. connection=null. ⚠ Con tarifa plana el cambio es del PLAN o de la cotización: `overageArs` y `overageMessages` llegan en 0 (sólo un plan a medida con cupo pactado los mueve). |

| `webhook.test` | — | El evento del botón 'Probar' del panel. NO es suscribible: se entrega SIEMPRE a ese endpoint (aunque tenga lista de eventos explícita) para validar conectividad + firma. connection=null, data.test=true. Nunca lo trates como tráfico real. |

**`message.received`** — data

```json
{
  "message": {
    "id": "wamid.HBgL…",
    "from": "5493511234567",
    "type": "text",
    "text": {
      "body": "hola"
    }
  },
  "contacts": [
    {
      "wa_id": "5493511234567",
      "profile": {
        "name": "Ana"
      }
    }
  ]
}
```

**`message.echo`** — data

```json
{
  "origin": "device",
  "message": {
    "id": "wamid.HBgL…",
    "from": "5493516516690",
    "to": "5493511234567",
    "type": "text",
    "timestamp": "1754531482",
    "text": {
      "body": "te confirmo el turno para mañana 10hs"
    }
  }
}
```

**`message.status`** — data

```json
{
  "messageId": "wamid.HBgL…",
  "status": "read",
  "origin": "device",
  "recipient": "5493511234567",
  "timestamp": "2026-08-06T00:31:25.000Z"
}
```

**`connection.created`** — data

```json
{
  "status": "connected"
}
```

**`connection.status_changed`** — data

```json
{
  "status": "disconnected",
  "previousStatus": "connected"
}
```

**`connection.usage_threshold_reached`** — data

```json
{
  "scope": "connection",
  "threshold": 90,
  "used": 900,
  "limit": 1000,
  "period": "2026-08",
  "connection": {
    "id": "conn_4eede070e5a84d1590bdce2ea1d837bc",
    "label": "Farmacia López",
    "externalId": "farmacia-lopez"
  }
}
```

**`usage.threshold_reached`** — data

```json
{
  "scope": "account",
  "threshold": 90,
  "used": 22610,
  "limit": 25000,
  "period": "2026-08"
}
```

**`history.synced`** — data

```json
{
  "conversations": 34,
  "messages": 512,
  "shared": true,
  "phase": 0
}
```

**`subscription.activated`** — data

```json
{
  "planCode": "growth",
  "periodEnd": "2026-09-13T00:00:00.000Z"
}
```

**`subscription.cancelled`** — data

```json
{
  "accessUntil": "2026-09-13T00:00:00.000Z"
}
```

**`billing.payment_failed`** — data

```json
{
  "paymentId": "123456789",
  "amount": 59000,
  "currency": "ARS"
}
```

**`billing.payment_recovered`** — data

```json
{
  "planCode": "growth",
  "paymentId": "123456789"
}
```

**`billing.amount_updated`** — data

```json
{
  "totalArs": 52500,
  "baseArs": 52500,
  "overageArs": 0,
  "overageMessages": 0
}
```

**`webhook.test`** — data

```json
{
  "type": "test",
  "test": true,
  "message": "WAIA Connect test event — your endpoint is reachable and verifying signatures. This is NOT real traffic."
}
```