Docs
ES

Goal

Confirm that your webhook endpoints are healthy, diagnose failed deliveries, and export delivery logs for audit. Endpoint creation and management (POST /v1/webhooks, PUT /v1/webhooks/{id}, etc.) is done through the admin panel. This how-to covers the monitoring and testing operations available on the user-facing API.

Prerequisites

  • An active API key (mxcep_…) with webhooks:read.
  • At least one webhook endpoint already registered (visible in the admin → Webhooks panel or via GET /v1/webhooks).
  • Your receiver must respond with HTTP 2xx and optionally validate the X-Signature-MexCep 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.example.com/v1/webhooks' \
  -H 'Authorization: Bearer mxcep_••••'
{
  "data": [
    {
      "type": "webhook_endpoint",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "attributes": {
        "url": "https://myapp.example.com/hooks/mexcep",
        "status": "active",
        "events": ["validation.completed", "validation_import.completed"],
        "created_at": "2025-02-01T12:00:00Z"
      }
    }
  ]
}

2. 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.example.com/v1/webhooks/f47ac10b-58cc-4372-a567-0e02b2c3d479/test' \
  -H 'Authorization: Bearer mxcep_••••'

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

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.example.com/v1/webhooks/deliveries' \
  -H 'Authorization: Bearer mxcep_••••'

5. Export delivery logs

Export logs for a specific endpoint or for all endpoints:

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

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

What's next