Docs
ES

Goal

Confirm that your webhook endpoints are healthy, diagnose failed deliveries, and export delivery logs for audit. It covers the full lifecycle from the API: register an endpoint, change it, rotate its secret and retire it, plus the monitoring and testing operations.

Prerequisites

  • An active API key (veriko_…). Reading and testing need webhooks:read; registering, changing and retiring need webhooks:create, webhooks:update and webhooks:delete.
  • A reachable HTTPS receiver. If you do not have an endpoint registered yet, step 2 creates one.
  • Your receiver must respond with HTTP 2xx and optionally validate the X-Webhook-Signature HMAC-SHA256 header.

Steps

1. List your endpoints

GET /v1/webhooks returns all registered endpoints with their status and subscribed events. The signing secret is not included — it is shown only once at creation time.

curl 'https://api.veriko.mx/v1/webhooks' \
  -H 'Authorization: Bearer veriko_••••'
{
  "data": [
    {
      "type": "webhook_endpoint",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "attributes": {
        "url": "https://myapp.veriko.mx/hooks/payments",
        "status": "active",
        "events": ["validation.completed", "validation_import.completed"],
        "created_at": "2025-02-01T12:00:00Z"
      }
    }
  ]
}

2. Register, update or retire an endpoint

These four operations can be called with your API key — they need the matching permission (webhooks:create, webhooks:update, webhooks:delete).

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

# Change the URL or the subscribed events
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"] }'

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

The signing secret is returned only once, at registration. If you lose it or suspect it leaked, rotate it:

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

3. Send a test event

After registering or updating an endpoint, send a synthetic test event to confirm your receiver is reachable and processes the signature correctly. Test deliveries do not count toward the consecutive-failure counter that auto-disables endpoints.

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

Successful response:

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

If delivered is false, the error field explains the problem (SSRF block, non-2xx response, etc.).

3. Inspect delivery logs for one endpoint

View the 50 most recent delivery attempts for a specific endpoint:

curl 'https://api.veriko.mx/v1/webhooks/f47ac10b-.../deliveries?per_page=50' \
  -H 'Authorization: Bearer veriko_••••'

Each entry shows the HTTP status code, response time, and a truncated response body — enough to diagnose most delivery failures without exposing full response payloads.

4. View deliveries across all endpoints

For a consolidated view of all delivery attempts regardless of endpoint:

curl 'https://api.veriko.mx/v1/webhooks/deliveries' \
  -H 'Authorization: Bearer veriko_••••'

5. Export delivery logs

Export logs for a specific endpoint or for all endpoints:

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

# All endpoints — XLSX
curl 'https://api.veriko.mx/v1/webhooks/deliveries/export?format=xlsx' \
  -H 'Authorization: Bearer veriko_••••' \
  --output all-webhook-deliveries.xlsx

What's next