Objetivo

Confirma que tus endpoints de webhook están en buen estado, diagnostica entregas fallidas y exporta logs de entrega para auditoría. Cubre el ciclo completo desde la API: registrar un endpoint, cambiarlo, rotar su secreto y retirarlo, además de las operaciones de monitoreo y prueba.

Requisitos previos

• Una API key activa (veriko_…). Leer y probar exige webhooks:read; registrar, cambiar y retirar exigen webhooks:create, webhooks:update y webhooks:delete.
• Un receptor HTTPS alcanzable. Si aún no tienes ningún endpoint registrado, el paso 2 lo crea.
• Tu receptor debe responder con HTTP 2xx y opcionalmente validar el encabezado HMAC-SHA256 X-Webhook-Signature.

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.veriko.mx/v1/webhooks' \
  -H 'Authorization: Bearer veriko_••••'

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

2. Registrar, actualizar o retirar un endpoint

Estas cuatro operaciones sí se pueden llamar con tu API key — necesitan el permiso correspondiente (webhooks:create, webhooks:update, webhooks:delete).

# Registrar
curl -X POST 'https://api.veriko.mx/v1/webhooks'   -H 'Authorization: Bearer veriko_••••'   -H 'Content-Type: application/json'   -d '{ "url": "https://miapp.veriko.mx/hooks/pagos", "events": ["validation.completed"] }'

# Cambiar la URL o los eventos suscritos
curl -X PUT 'https://api.veriko.mx/v1/webhooks/f47ac10b-58cc-4372-a567-0e02b2c3d479'   -H 'Authorization: Bearer veriko_••••'   -H 'Content-Type: application/json'   -d '{ "events": ["validation.completed", "validation_import.completed"] }'

# Retirar
curl -X DELETE 'https://api.veriko.mx/v1/webhooks/f47ac10b-58cc-4372-a567-0e02b2c3d479'   -H 'Authorization: Bearer veriko_••••'

El secret de firma se devuelve una sola vez, al registrar. Si lo pierdes o sospechas que se filtró, rótalo:

curl -X POST 'https://api.veriko.mx/v1/webhooks/f47ac10b-.../regenerate-secret'   -H 'Authorization: Bearer veriko_••••'

3. 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.veriko.mx/v1/webhooks/f47ac10b-58cc-4372-a567-0e02b2c3d479/test' \
  -H 'Authorization: Bearer veriko_••••'

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.veriko.mx/v1/webhooks/f47ac10b-.../deliveries?per_page=50' \
  -H 'Authorization: Bearer veriko_••••'

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.veriko.mx/v1/webhooks/deliveries' \
  -H 'Authorization: Bearer veriko_••••'

5. Exportar logs de entrega

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

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

# Todos los endpoints — XLSX
curl 'https://api.veriko.mx/v1/webhooks/deliveries/export?format=xlsx' \
  -H 'Authorization: Bearer veriko_••••' \
  --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.