Webhooks & Events

Receive real-time HTTP POST notifications when critical operations, compliance checks, or divisional updates occur across the Aevum Zenth ecosystem. Build resilient integrations with our event-driven API.

Quick Start

1 Generate a Webhook Secret

Navigate to Developer Console > Integrations > Webhooks. Create a new endpoint and copy the generated WEBHOOK_SECRET. This is used for HMAC-SHA256 signature verification.

2 Configure Your Endpoint

Provide a publicly accessible HTTPS URL. Aevum Zenth will send a webhook.ping event to verify connectivity. Respond with 200 OK or 202 Accepted within 5 seconds.

3 Subscribe to Events

Select event types via the dashboard or API. Filter by division, region, or priority. Unsubscribed events are silently dropped at our edge network.

4 Verify & Process

Validate the X-Aevum-Signature header against your secret. Parse the JSON payload and acknowledge receipt. Implement idempotency using webhook_id.

Event Catalog

Aevum Zenth emits events across all 400+ subsidiaries. Common event types include:

Event Name Description Scope Type
division.created New subsidiary or operational unit registered Global Core
transaction.completed Financial settlement finalized across Capital Group Finance Core
compliance.audit.triggered Automated regulatory check initiated Legal/Compliance Compliance
sensor.alert.threshold IoT/Infrastructure metric exceeded safe bounds Energy/Industrial System
shipment.updated Logistics status change (customs, transit, delivery) Logistics Core
contract.signed Legal agreement executed via digital signature Legal/Enterprise Core

Payload Structure

All webhook payloads are JSON-encoded. The structure is consistent across event types:

{
  "webhook_id": "whk_9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c",
  "event_type": "transaction.completed",
  "timestamp": 1718923456789,
  "division": "Aevum Capital Group",
  "region": "EMEA",
  "data": {
    "transaction_id": "txn_8837f9a2b1c4d5e6",
    "amount": 1250000.00,
    "currency": "USD",
    "status": "settled"
  },
  "metadata": {
    "retry_count": 0,
    "source_ip": "203.0.113.42"
  }
}

Signature Verification

Every webhook request includes an HMAC-SHA256 signature in the X-Aevum-Signature header. Always verify before processing.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.write(payload);
  hmac.end();
  const digest = hmac.read().toString('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

Headers included in every request:

  • X-Aevum-Signature: HMAC-SHA256 hex digest
  • X-Aevum-Timestamp: Unix epoch (milliseconds)
  • X-Webhook-Id: Unique ID for deduplication
  • Content-Type: application/json

Delivery & Reliability

Retry Policy

If your endpoint returns a 5xx error or fails to respond within 5 seconds, Aevum Zenth retries with exponential backoff:

  • 1st retry: 30 seconds
  • 2nd retry: 2 minutes
  • 3rd retry: 10 minutes
  • 4th retry: 1 hour
  • 5th retry: 6 hours
  • Final retry: 24 hours

Idempotency & Deduplication

Always check the webhook_id before processing. Events may be delivered more than once during network partitions. Store processed IDs in a local set or database to prevent duplicate actions.

Testing & Debugging

Use the Webhook Tester in the Developer Console to:

  • Simulate specific event types with mock payloads
  • View delivery logs, response codes, and latency metrics
  • Replay failed events from the last 30 days
  • Generate test signatures locally

For production readiness, monitor your 4xx and 5xx rates. Sustained failure rates above 5% will temporarily disable the endpoint to protect our event bus.