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

# Introducción a Webhooks

> Recibí eventos en tiempo real cuando llegan mensajes, cambian estados o se crean contactos/conversaciones.

Waspy entrega eventos a tu URL como `POST` HTTP firmado. Es la forma recomendada de integrar bots y CRMs externos: te enterás del evento en cuanto sucede, sin necesidad de hacer polling.

## Eventos soportados

| Evento                   | Cuándo dispara                                                          |
| ------------------------ | ----------------------------------------------------------------------- |
| `message.received`       | Llega un mensaje entrante de un contacto                                |
| `message.status_changed` | Cambia el estado de un mensaje saliente (sent, delivered, read, failed) |
| `conversation.created`   | Se crea una conversación nueva                                          |
| `contact.created`        | Se crea un contacto nuevo                                               |

## Crear una suscripción

```bash theme={null}
curl -X POST https://api.waspytech.com/api/v2/webhooks \
  -H "Authorization: Bearer wspy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-bot.example.com/webhook/waspy",
    "events": ["message.received", "message.status_changed"],
    "description": "Bot de soporte"
  }'
```

Respuesta `201` (el `secret` se devuelve **una sola vez** — guardalo):

```json theme={null}
{
  "data": {
    "id": "uuid",
    "url": "https://tu-bot.example.com/webhook/waspy",
    "events": ["message.received", "message.status_changed"],
    "secret": "whsec_abc123...",
    "enabled": true,
    "createdAt": "2026-04-19T12:00:00.000Z"
  },
  "meta": { "requestId": "..." }
}
```

**Scopes requeridos:** `webhooks:read` para listar/consultar, `webhooks:write` para crear/actualizar/borrar/test/replay.

## Aislamiento por tenant

Cada suscripción está atada a tu API key, y por lo tanto a tu tenant. **Solo recibís eventos de tu propia cuenta.** Nunca ves datos de otros tenants.

## Reintentos y auto-disable

Si tu URL devuelve un código no-2xx o no responde en 10s, Waspy reintenta automáticamente:

| Intento  | Espera antes |
| -------- | ------------ |
| 2        | 1 minuto     |
| 3        | 5 minutos    |
| 4        | 30 minutos   |
| 5        | 2 horas      |
| (último) | 12 horas     |

Después de **10 entregas consecutivas fallidas** la suscripción se auto-desactiva (`enabled: false`, `disabledReason` poblado). Para reactivarla, hacé `PATCH /webhooks/:id` con `enabled: true`.

## Probar antes de producción

```bash theme={null}
curl -X POST https://api.waspytech.com/api/v2/webhooks/{id}/test \
  -H "Authorization: Bearer wspy_..."
```

Esto encola un evento sintético `message.received` con datos dummy para que validés tu firma + URL.

## Próximos pasos

* [Catálogo de eventos y payloads](/webhooks/events)
* [Verificación de firma HMAC](/webhooks/security)
* [API reference](/api-reference/webhooks)