Webhook Signature Verification

VeriSwarm signs every webhook delivery with HMAC-SHA256 so you can verify the payload was not tampered with in transit.

Headers

Every webhook delivery includes:

Header	Description
X-VeriSwarm-Signature	HMAC-SHA256 hex digest of the request body
X-VeriSwarm-Timestamp	Unix timestamp (seconds) when the webhook was sent
X-VeriSwarm-Delivery-Id	Unique delivery ID for idempotency

Verification Steps

1. Read the X-VeriSwarm-Signature and X-VeriSwarm-Timestamp headers
2. Concatenate {timestamp}.{raw_body} (the timestamp, a dot, and the raw request body bytes)
3. Compute HMAC-SHA256 using your webhook signing secret as the key
4. Compare the computed hex digest with the signature header (use constant-time comparison)
5. Optionally check the timestamp is within 5 minutes to prevent replay attacks

Python Example

import hmac
import hashlib
import time

def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Check timestamp freshness (optional but recommended)
    if abs(time.time() - int(timestamp)) > 300:
        return False  # Older than 5 minutes

    # Compute expected signature
    message = f"{timestamp}.{raw_body.decode('utf-8')}".encode("utf-8")
    expected = hmac.HMAC(
        key=secret.encode("utf-8"),
        msg=message,
        digestmod=hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(expected, signature)


# Usage in Flask
@app.route("/webhooks/veriswarm", methods=["POST"])
def handle_veriswarm_webhook():
    raw_body = request.get_data()
    signature = request.headers.get("X-VeriSwarm-Signature", "")
    timestamp = request.headers.get("X-VeriSwarm-Timestamp", "")

    if not verify_webhook(raw_body, signature, timestamp, WEBHOOK_SECRET):
        return "Invalid signature", 401

    payload = request.get_json()
    # Process the event...
    return "OK", 200

Node.js Example

const crypto = require("crypto");

function verifyWebhook(rawBody, signature, timestamp, secret) {
  // Check timestamp freshness
  if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
    return false;
  }

  const message = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(message)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );
}

// Usage in Express
app.post("/webhooks/veriswarm", express.raw({ type: "*/*" }), (req, res) => {
  const rawBody = req.body.toString();
  const signature = req.headers["x-veriswarm-signature"] || "";
  const timestamp = req.headers["x-veriswarm-timestamp"] || "";

  if (!verifyWebhook(rawBody, signature, timestamp, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(rawBody);
  // Process the event...
  res.status(200).send("OK");
});

Webhook Event Types

Event	Description
*	Wildcard -- subscribe to all event types
decision.checked	A trust decision was made (includes agent_id, decision, reason_code)
provider.report.ingested	An event/report was ingested
agent.killed	An agent's kill switch was activated (Guard)
agent.unkilled	An agent's kill switch was deactivated (Guard)
agent.verified	An agent's identity was verified (Passport)
score.updated	An agent's trust scores were recalculated
flag.created	A moderation flag was raised

Testing

Use the webhook test endpoint to send a test delivery to your configured URL:

curl -X POST https://api.veriswarm.ai/v1/public/providers/webhooks/{webhook_id}/test \
  -H "x-account-access-token: YOUR_TOKEN"

Retry Policy

Failed deliveries are retried with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: 30 seconds
• Attempt 3: 2 minutes
• Attempt 4: 5 minutes
• Final: Marked as exhausted, alert sent to admin