Objetivo

Confirma que tus endpoints de webhook están en buen estado, diagnostica entregas fallidas y exporta logs de entrega para auditoría. La creación y gestión de endpoints (POST /v1/webhooks, PUT /v1/webhooks/{id}, etc.) se realiza desde el panel de administración. Este how-to cubre las operaciones de monitoreo y prueba disponibles en la API orientada al usuario.

Requisitos previos

• Una API key activa (mxcep_…) con el permiso webhooks:read.
• Al menos un endpoint de webhook ya registrado (visible en el panel admin → Webhooks o via GET /v1/webhooks).
• Tu receptor debe responder con HTTP 2xx y opcionalmente validar el header HMAC-SHA256 X-Signature-MexCep.

Pasos

1. Listar tus endpoints

GET /v1/webhooks devuelve todos los endpoints registrados con su estado y eventos suscritos. El secret de firma no se incluye — solo se muestra una vez en el momento de la creación.

curl 'https://api.example.com/v1/webhooks' \
  -H 'Authorization: Bearer mxcep_••••'

{
  "data": [
    {
      "type": "webhook_endpoint",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "attributes": {
        "url": "https://miapp.example.com/hooks/mexcep",
        "status": "active",
        "events": ["validation.completed", "validation_import.completed"],
        "created_at": "2025-02-01T12:00:00Z"
      }
    }
  ]
}

2. Enviar un evento de prueba

Después de registrar o actualizar un endpoint, envía un evento de prueba sintético para confirmar que tu receptor es alcanzable y procesa la firma correctamente. Las entregas de prueba no cuentan hacia el contador de fallos consecutivos que deshabilita endpoints automáticamente.

curl -X POST \
  'https://api.example.com/v1/webhooks/f47ac10b-58cc-4372-a567-0e02b2c3d479/test' \
  -H 'Authorization: Bearer mxcep_••••'

Respuesta exitosa:

{
  "data": {
    "type": "webhook_test_result",
    "attributes": {
      "delivered": true,
      "http_status": 200,
      "response_time_ms": 143
    }
  }
}

Si delivered es false, el campo error explica el problema (bloqueo SSRF, respuesta no 2xx, etc.).

3. Inspeccionar logs de entrega de un endpoint

Ver los 50 intentos de entrega más recientes de un endpoint específico:

curl 'https://api.example.com/v1/webhooks/f47ac10b-.../deliveries?per_page=50' \
  -H 'Authorization: Bearer mxcep_••••'

Cada entrada muestra el código de estado HTTP, el tiempo de respuesta y un cuerpo de respuesta truncado — suficiente para diagnosticar la mayoría de los fallos de entrega sin exponer los payloads completos.

4. Ver entregas de todos los endpoints

Para una vista consolidada de todos los intentos de entrega independientemente del endpoint:

curl 'https://api.example.com/v1/webhooks/deliveries' \
  -H 'Authorization: Bearer mxcep_••••'

5. Exportar logs de entrega

Exporta logs de un endpoint específico o de todos los endpoints:

# Un endpoint — CSV
curl 'https://api.example.com/v1/webhooks/f47ac10b-.../deliveries/export?format=csv' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output webhook-entregas-f47ac10b.csv

# Todos los endpoints — XLSX
curl 'https://api.example.com/v1/webhooks/deliveries/export?format=xlsx' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output todas-las-entregas.xlsx

Siguientes pasos

• Monitorear el consumo de cuota API y ciclo de facturación: ver Monitorear uso.
• Analizar tendencias de validaciones y patrones por contraparte: ver Analizar insights.