Webhooks

Receive real-time HTTP notifications when events occur across your Aevum Zenth integrations. Configure endpoints, verify signatures, and build resilient event-driven architectures.

Enterprise Ready: Webhooks support HMAC-SHA256 signature verification, idempotency keys, and automatic retry queues with configurable jitter. All payloads are delivered over TLS 1.3.

Overview

Webhooks allow your systems to react instantly to changes in Aevum Zenth services without polling. When an event is triggered, we send a POST request to your registered endpoint containing a structured JSON payload.

                    HTTP Request
                    
                
POST https://your-domain.com/webhooks/aevum
Host: your-domain.com
Content-Type: application/json
X-Aevum-Signature: t=1735084400,v1=a8f3b2c1...
X-Aevum-Event-ID: evt_8f92a1c3
X-Aevum-Retry-Count: 0

Security & Signature Verification

Every webhook payload is signed using HMAC-SHA256. You must verify the signature before processing the event to prevent spoofed requests.

Header	Description
X-Aevum-Signature	Comma-separated key=value pairs containing timestamp and signature.
X-Aevum-Event-ID	Unique identifier for the event. Use for idempotency.
X-Aevum-Retry-Count	Integer indicating retry attempt (0 = initial delivery).

⚠️ Critical: Always validate the timestamp within a 5-minute tolerance window. Reject payloads with expired or future timestamps to prevent replay attacks.

Retry Policy

If your endpoint fails to respond with a 2xx status code, Aevum Zenth automatically retries delivery using an exponential backoff strategy:

Attempt 1: Immediate
Attempt 2: 30 seconds
Attempt 3: 2 minutes
Attempt 4: 10 minutes
Attempt 5: 1 hour
Attempt 6+: 12 hours (up to 3 days max)

After final failure, events are routed to the Dead Letter Queue (DLQ) for manual inspection and reprocessing.

Endpoint Configuration

Create webhook endpoints via the Developer Console or the POST /v1/webhooks API endpoint. Each endpoint supports multiple event subscriptions.

                    cURL
                    
                
curl -X POST https://api.aevumzenth.com/v1/webhooks \
  -H "Authorization: Bearer $AZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.your-app.com/aevum",
    "events": ["payment.completed", "invoice.issued"],
    "active": true
  }'

Event Catalog

Event Name	Description	Division
payment.completed	Fund transfer successfully settled.	Finance
payment.failed	Transaction declined or timed out.	Finance
invoice.issued	New billing document generated.	Finance
grid.status.update	Renewable output or load changes.	Energy
shipment.tracked	Logistics node scan or transit update.	Logistics
compliance.alert	Risk or regulatory flag triggered.	Global Ops

Code Examples

Python (Flask)

                    Python
                    
                
import hashlib, hmac, json, os
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["AZ_WEBHOOK_SECRET"]

def verify_signature(payload, sig_header):
    timestamp, signature = sig_header.split(",")
    timestamp = timestamp.split("=")[1]
    signature = signature.split("=")[1]
    
    expected = hmac.new(
        SECRET.encode(), f"{timestamp}{payload}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route("/webhooks/aevum", methods=["POST"])
def webhook():
    sig = request.headers.get("X-Aevum-Signature")
    payload = request.get_data()
    
    if not verify_signature(payload, sig):
        return "Invalid signature", 401
        
    event = json.loads(payload)
    process_event(event)
    return "OK", 200

Node.js (Express)

                    JavaScript
                    
                
const crypto = require("crypto");
const express = require("express");
const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/aevum", (req, res) => {
  const sig = req.headers["x-aevum-signature"];
  const [ts, sigHash] = sig.split(",").map(k => k.split("=")[1]);
  
  const mac = crypto.createHmac("sha256", process.env.AZ_WEBHOOK_SECRET)
    .update(ts + req.body).digest("hex");
    
  if (!crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sigHash))) {
    return res.status(401).send("Invalid signature");
  }
  
  processEvent(JSON.parse(req.body));
  res.status(200).send("OK");
});

Troubleshooting

Issue	Cause	Resolution
Signature mismatch	Secret key rotation or payload modification	Verify `AZ_WEBHOOK_SECRET` matches console value.
Timeout errors	Endpoint takes > 5s to respond	Return `200 OK` immediately, process async.
SSL/TLS handshake failure	Self-signed certs or TLS < 1.2	Use valid CA-signed certificates.
Idempotency conflicts	Duplicate event IDs processed	Implement unique index on `X-Aevum-Event-ID`.

Best Practices

Always verify signatures before parsing or acting on payloads.
Respond quickly: Acknowledge receipt with 200 OK within 5 seconds.
Handle duplicates: Webhooks may retry; use X-Aevum-Event-ID for deduplication.
Use HTTPS only: Aevum Zenth drops non-TLS endpoints automatically.
Monitor DLQ: Set up alerts for failed deliveries requiring manual intervention.