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.

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

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

Reintentos y auto-disable

Probar antes de producción

Próximos pasos

​Eventos soportados

​Crear una suscripción

​Aislamiento por tenant

​Reintentos y auto-disable

​Probar antes de producción

​Próximos pasos

Eventos soportados

Crear una suscripción

Aislamiento por tenant

Reintentos y auto-disable

Probar antes de producción

Próximos pasos