Webhook Integration Guide

ValidonX can send real-time notifications to your server when events occur in your tenant workspace. This guide covers webhook setup, event types, payload format, and signature verification.

Setting Up Webhooks

1. Navigate to Webhooks in your dashboard
2. Add an endpoint URL (must be HTTPS in production)
3. Select which events to subscribe to
4. Save and test the endpoint

Event Types

Event	Description
license.created	A new license key was created
license.revoked	A license key was revoked
activation.created	A new activation was recorded
activation.revoked	An activation was revoked
entitlement.granted	An entitlement was granted to the tenant
entitlement.revoked	An entitlement was revoked
subscription.created	A subscription was created
subscription.updated	A subscription was modified (plan change, renewal)
subscription.cancelled	A subscription was cancelled
usage.threshold_reached	Usage hit 80% or 100% of plan limit

Payload Format

All webhook payloads follow a consistent structure:

{
  "id": "evt_01H8XXXXXXXXXXXXX",
  "type": "license.created",
  "version": "1",
  "tenant_id": "uuid",
  "created_at": "2026-04-03T10:00:00Z",
  "data": {
    "license_id": "uuid",
    "license_key": "VALIDONX-XXXX-XXXX-XXXX-XXXX",
    "status": "active"
  }
}

Signature Verification

Every webhook delivery includes an X-ValidonX-Signature header containing an HMAC-SHA256 signature of the payload body, signed with your webhook signing secret.

Verifying in PHP

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_VALIDONX_SIGNATURE'];
$secret = 'your-webhook-signing-secret';

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
// Process event...

Verifying in Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Retry Policy

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff:

Attempt	Delay
1	1 minute
2	5 minutes
3	30 minutes
4	1 hour
5	4 hours (final attempt)

After 5 failed attempts, the event is moved to a dead-letter queue.

Circuit Breaker

If an endpoint accumulates 10 consecutive failures, ValidonX temporarily disables deliveries for 30 minutes (circuit breaker). Deliveries resume automatically after the cooldown period. You'll receive an email notification when this happens.

Best Practices

1. Return 200 quickly: Process events asynchronously — acknowledge receipt first, process later
2. Handle duplicates: Events may be delivered more than once — use the event id for idempotency
3. Verify signatures: Always verify the X-ValidonX-Signature header to prevent spoofing
4. Use HTTPS: Webhook endpoints must use HTTPS in production
5. Monitor failures: Check the webhook delivery logs in your dashboard regularly