API de Webhooks

Endpoints para gestionar suscripciones de webhook. Todos los endpoints de webhook requieren el plan PRO y el permiso config:manage (solo Owner).

Eventos disponibles:

• quote.created — Se creó una nueva cotización
• quote.status_changed — Se actualizó el estado de una cotización
• quote.sent — Se envió una cotización por correo electrónico
• client.created — Se agregó un nuevo cliente
• product.created — Se agregó un nuevo producto

Verificación de firma: Cada entrega de webhook incluye un header X-Cotizera-Signature (HMAC-SHA256) y un header X-Cotizera-Event con el nombre del evento.

Listar Webhooks

GET /api/webhooks

Permiso: config:manage | Plan: PRO

Lista todos los webhooks del tenant actual, incluyendo conteos de entregas.

Respuesta 200 OK:

[
  {
    "id": "clxyz...",
    "url": "https://mi-servidor.mx/webhook",
    "events": ["quote.created", "quote.status_changed"],
    "secret": "whsec_abc123...",
    "isActive": true,
    "tenantId": "...",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-15T10:00:00.000Z",
    "_count": { "deliveries": 47 }
  }
]

Crear Webhook

POST /api/webhooks

Permiso: config:manage | Plan: PRO

Crea una nueva suscripción de webhook. Devuelve el secret generado para la verificación de firma.

Cuerpo de la solicitud:

{
  "url": "https://mi-servidor.mx/webhook",
  "events": ["quote.created", "client.created"]
}

Respuesta 201 Created: Devuelve el webhook creado incluyendo el secret.

Obtener un Webhook

GET /api/webhooks/:id

Permiso: config:manage | Plan: PRO

Obtiene un webhook individual con su conteo de entregas.

Respuesta 200 OK: Devuelve el objeto del webhook.

Errores:

Actualizar Webhook

PUT /api/webhooks/:id

Permiso: config:manage | Plan: PRO

Actualiza la URL, los eventos o el estado activo de un webhook. Todos los campos son opcionales.

Cuerpo de la solicitud:

{
  "url": "https://nuevo-servidor.mx/webhook",
  "events": ["quote.created", "quote.status_changed", "client.created"],
  "isActive": true
}

Respuesta 200 OK: Devuelve el webhook actualizado.

Eliminar Webhook

DELETE /api/webhooks/:id

Permiso: config:manage | Plan: PRO

Elimina permanentemente un webhook y todo su historial de entregas.

Respuesta 200 OK:

{
  "ok": true
}

Probar Webhook

POST /api/webhooks/:id/test

Permiso: config:manage | Plan: PRO

Envía un payload de prueba a la URL del webhook. El evento de prueba es webhook.test y la entrega se registra en el historial. Tiene un timeout de 5 segundos.

Cuerpo de la solicitud: No se requiere.

Respuesta 200 OK:

{
  "success": true,
  "statusCode": 200
}

Payload de prueba enviado:

{
  "event": "webhook.test",
  "timestamp": "2026-03-31T10:00:00.000Z",
  "data": { "message": "Este es un evento de prueba" }
}

Errores:

Historial de Entregas

GET /api/webhooks/:id/deliveries

Permiso: config:manage | Plan: PRO

Obtiene el historial paginado de entregas de un webhook.

Parámetros de consulta:

Respuesta 200 OK:

{
  "data": [
    {
      "id": "clxyz...",
      "webhookId": "...",
      "event": "quote.created",
      "payload": { ... },
      "statusCode": 200,
      "responseBody": "OK",
      "deliveredAt": "2026-03-31T10:00:01.000Z",
      "createdAt": "2026-03-31T10:00:00.000Z"
    }
  ],
  "total": 47,
  "page": 1,
  "totalPages": 3
}