Overview

Push validation events to external systems in real-time via webhooks. Each webhook is signed with HMAC-SHA256 for security and can be configured to fire on specific event types.

How It Works

1. Create a webhook with:
– Target URL
– Event types to subscribe to
– HMAC-SHA256 secret for signature verification
2. Events include:
– Validation completed
– Score regression detected
– Schema change detected
– Alert triggered
3. Webhook payloads include full event data
4. Auto-disabled after 5 consecutive delivery failures
5. Test endpoint available for verification

Tier Availability

| Tier | Available |
|——|———–|
| Enterprise | Yes |

Related Features

– API Key Management: Alternative integration method (pull vs push)
– Custom Alert Rules: Rules can trigger webhooks
– Audit Trail: Webhook deliveries are logged

Mini-Tutorial

Step 1: Prepare Your Endpoint

Create an HTTPS endpoint on your server that can receive POST requests and handle ValidGraph webhook payloads.

Step 2: Create a Webhook

Navigate to Enterprise > Webhooks and click “Add Webhook.”

Step 3: Configure Target URL

Enter your endpoint URL (must be HTTPS). Webhooks are sent to this address.

Step 4: Choose Events

Select which events trigger webhook deliveries:
– Validation failed
– Score dropped (regression detected)
– Schema changed
– Schema removed

Step 5: Set Signing Secret

Create a shared secret for HMAC-SHA256 signature verification. Keep this secret safe.

Step 6: Test Webhook

Click “Send Test Webhook” to verify your endpoint receives and processes payloads correctly.

Step 7: Activate

Enable the webhook. It now receives real events.

Step 8: Monitor & Debug

View recent webhook deliveries and any failures in the webhook details page.

Technical Details

Create Webhook

POST /api/v1/webhooks
X-API-Key: sk_live_abc123...
Content-Type: application/json

{
  "url": "https://myapp.example.com/webhooks/validgraph",
  "events": [
    "validation.failed",
    "score.dropped"
  ],
  "secret": "whsec_1a2b3c4d5e6f..."
}

Response:

{
  "id": "webhook_xyz789",
  "url": "https://myapp.example.com/webhooks/validgraph",
  "events": ["validation.failed", "score.dropped"],
  "status": "active",
  "created_at": "2025-03-22T14:30:00Z",
  "last_triggered_at": null
}

Webhook Payload Example (validation.failed)

{
  "event": "validation.failed",
  "timestamp": "2025-03-22T14:30:00Z",
  "data": {
    "validation_id": "val_12345",
    "url": "https://example.com/page",
    "project_id": "proj_abc123",
    "status": "invalid",
    "schema_type": "Article",
    "errors": [
      {
        "property": "headline",
        "message": "Property is required"
      }
    ]
  }
}

Webhook Payload Example (score.dropped)

{
  "event": "score.dropped",
  "timestamp": "2025-03-22T14:30:00Z",
  "data": {
    "project_id": "proj_abc123",
    "previous_score": 88,
    "current_score": 72,
    "change": -16,
    "url": "https://example.com/updated-page"
  }
}

Signature Verification (HMAC-SHA256)

All webhooks include an X-SVS-Signature header:

X-SVS-Signature: sha256=abcd1234efgh5678...

Verify the signature in your endpoint:

import hmac
import hashlib

def verify_webhook(body_raw, signature, secret):
    expected = hmac.new(
        secret.encode(),
        body_raw.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

In your Flask/Express endpoint:
signature = request.headers.get('X-SVS-Signature').split('=')[1]
verified = verify_webhook(request.data.decode(), signature, webhook_secret)
if not verified:
    return {"error": "Signature mismatch"}, 401

Auto-Disable on Failures

After 5 consecutive delivery failures, the webhook is automatically disabled:

{
  "id": "webhook_xyz789",
  "status": "disabled_too_many_failures",
  "last_error": "Connection timeout",
  "failure_count": 5
}

Re-enable via dashboard or API after fixing the issue.

Test Webhook

POST /api/v1/webhooks/webhook_xyz789/test
X-API-Key: sk_live_abc123...

Sends a test payload with event type “webhook.test” to verify connectivity.

References

– Webhook Best Practices
– HMAC-SHA256 Signature Standard (RFC 4868)
– Webhook Security (OWASP)
– ValidGraph Webhook Documentation