Introducción a Webhooks

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

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):

{
  "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.

Códigos que cuentan como entrega

Waspy marca la entrega como exitosa cuando tu URL responde:

2xx — el evento se recibió.
Cualquier 3xx (301, 302, 303, 307, 308 y el resto) — el POST ya se ejecutó. Guardamos el status real (por ejemplo 302) y no reintentamos.

El caso típico es Google Apps Script (script.google.com / script.googleusercontent.com): doPost corre y después el runtime responde 302. Eso no es un fallo. Si lo contáramos como error, Waspy reintentaría el mismo evento (y tu script lo procesaría de nuevo) y, a las 10 fallas seguidas, desactivaría la suscripción. No volvemos a mandar el POST a la URL de Location. Seguir el redirect con POST re-ejecutaría el handler y, si el Location apuntara a una IP interna, se saltearía la validación del destino. Si la respuesta trae Location, hacemos un GET a esa URL únicamente para dejar asentado en el registro de la entrega qué devolvió el redirect. Antes de ese GET se vuelve a validar el destino con las mismas reglas que la URL de la suscripción. Si el GET falla, no hay Location, o el destino no es seguro, la entrega sigue contando como exitosa: el GET no cambia el resultado. La misma regla vale para las entregas reales, para POST /webhooks/:id/test y para el reenvío manual POST /webhooks/:id/replay/:deliveryId. Un 4xx, un 5xx o una URL que no responde en 10 segundos es una entrega fallida.

Reintentos y auto-disable

Si la entrega falla, 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

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.

Empezar

Fundamentos

Conceptos

Webhooks

Otros

Introducción a Webhooks

Eventos soportados

Crear una suscripción

Aislamiento por tenant

Códigos que cuentan como entrega

Reintentos y auto-disable

Probar antes de producción

Próximos pasos

​Eventos soportados

​Crear una suscripción

​Aislamiento por tenant

​Códigos que cuentan como entrega

​Reintentos y auto-disable

​Probar antes de producción

​Próximos pasos

Eventos soportados

Crear una suscripción

Aislamiento por tenant

Códigos que cuentan como entrega

Reintentos y auto-disable

Probar antes de producción

Próximos pasos