Webhooks

Las suscripciones se gestionan vía API REST. Cada operación está scoped al tenant de tu API key — nunca podés ver ni modificar suscripciones de otros tenants. Scopes: webhooks:read (GET), webhooks:write (POST/PATCH/DELETE/test/replay).

GET /webhooks

Lista las suscripciones del tenant.

curl https://api.waspytech.com/api/v2/webhooks \
  -H "Authorization: Bearer wspy_..."

POST /webhooks

Crea una suscripción nueva. El secret se devuelve una sola vez.

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"
  }'

Campo	Tipo	Requerido	Descripción
`url`	string (URL HTTPS)	Sí	Endpoint que recibe los POST
`events`	string[]	Sí	Uno o más de los eventos válidos
`description`	string	No	Etiqueta libre para tu propio uso

GET /webhooks/:id

Devuelve una suscripción individual (sin secret).

PATCH /webhooks/:id

Actualiza url, events, description o enabled. Si pasás enabled: true, se limpia el estado de auto-disable y se resetea el contador de fallas.

DELETE /webhooks/:id

Borra la suscripción.

POST /webhooks/:id/test

Encola un evento sintético message.received con datos dummy. Útil para validar firma + URL en desarrollo.

Test deliveries SÍ aparecen en GET /webhooks/:id/deliveries (con statusCode, errorMessage, etc), pero NO actualizan lastDeliveryAt, lastDeliveryStatus ni consecutiveFailures en la subscription — para no mezclar bookkeeping de pruebas con producción. Si querés confirmar que el test golpeó tu endpoint, consultá GET /webhooks/:id/deliveries?status=all&limit=5 justo después.

La response incluye samplePayload con el envelope exacto que se va a entregar a tu URL — útil para configurar la verificación de firma localmente antes de triggerear:

{
  "data": {
    "subscriptionId": "uuid",
    "enqueued": true,
    "event": "message.received",
    "samplePayload": {
      "event": "message.received",
      "webhookId": "uuid",
      "deliveredAt": "2026-04-19T...",
      "attempt": 1,
      "data": { /* MessagePublic + contact */ }
    }
  },
  "meta": { "requestId": "..." }
}

GET /webhooks/:id/deliveries

Lista los intentos de entrega individuales de una suscripción. Cada delivery (incluso fallido) genera una fila acá. Cursor-based, newest first. Scope: webhooks:read

Query	Default	Descripción
`cursor`	—	Cursor opaco de la respuesta anterior
`limit`	`50`	Resultados por página (máx 100)
`status`	`all`	`success`, `failed` o `all`

curl "https://api.waspytech.com/api/v2/webhooks/{id}/deliveries?status=failed&limit=20" \
  -H "Authorization: Bearer wspy_..."

Response:

{
  "data": [
    {
      "id": "delivery-uuid",
      "subscriptionId": "sub-uuid",
      "event": "message.received",
      "attempt": 3,
      "success": false,
      "statusCode": 500,
      "errorMessage": null,
      "responseBodyTruncated": "Internal server error",
      "payloadHash": "sha256-hex",
      "deliveredAt": null,
      "createdAt": "2026-04-19T..."
    }
  ],
  "meta": { "requestId": "...", "cursor": "...", "hasMore": true }
}

Los id que devuelve son los deliveryId que podés pasarle a POST /webhooks/:id/replay/:deliveryId.

POST /webhooks/:id/rotate-secret

Genera un nuevo secret HMAC e invalida el anterior inmediatamente. Las entregas en cola que se hayan firmado con el secret viejo van a fallar la verificación en tu endpoint. Scope: webhooks:write

curl -X POST https://api.waspytech.com/api/v2/webhooks/{id}/rotate-secret \
  -H "Authorization: Bearer wspy_..."

{
  "data": {
    "id": "sub-uuid",
    "secret": "whsec_NUEVO_SECRET_AQUI"
  },
  "meta": { "requestId": "..." }
}

El nuevo secret se devuelve una sola vez. Guardalo y actualizá tu WASPY_WEBHOOK_SECRET antes de la próxima delivery.

POST /webhooks/:id/replay/:deliveryId

Re-encola un delivery histórico (de la tabla webhook_deliveries). Útil para reintentar manualmente entregas que fallaron después de exhaustar reintentos automáticos.

El payload exacto del delivery original no se almacena verbatim (sólo su hash). El replay re-fires un evento con el mismo event y datos sintéticos — tu integración debe ser idempotente sobre data.id para que esto sea seguro.

Introducción

Recursos

GET /webhooks

POST /webhooks

GET /webhooks/:id

PATCH /webhooks/:id

DELETE /webhooks/:id

POST /webhooks/:id/test

GET /webhooks/:id/deliveries

POST /webhooks/:id/rotate-secret

POST /webhooks/:id/replay/:deliveryId

​GET /webhooks

​POST /webhooks

​GET /webhooks/:id

​PATCH /webhooks/:id

​DELETE /webhooks/:id

​POST /webhooks/:id/test

​GET /webhooks/:id/deliveries

​POST /webhooks/:id/rotate-secret

​POST /webhooks/:id/replay/:deliveryId

GET /webhooks

POST /webhooks

GET /webhooks/:id

PATCH /webhooks/:id

DELETE /webhooks/:id

POST /webhooks/:id/test

GET /webhooks/:id/deliveries

POST /webhooks/:id/rotate-secret

POST /webhooks/:id/replay/:deliveryId