Webhooks¶

Vex Raptor can call your endpoints when scans complete or findings cross a threshold — and it accepts inbound CI webhooks to gate builds.

Outbound: scan events¶

Register a webhook URL (console → Triggers) to receive an event when a scan finishes or a rule fires. The payload:

{
  "event": "scan.completed",
  "scan_id": "scan_01H...",
  "org_id": 42,
  "target": "https://app.example.com",
  "verdict": "fail",
  "totals": { "critical": 1, "high": 3, "medium": 5 },
  "risk_score": 78,
  "created_at": "2026-07-09T12:00:00Z"
}

Events: scan.started, scan.completed, finding.confirmed, rule.triggered.

Verify the signature¶

Every outbound request is signed so you can prove it came from Vex Raptor and was not tampered with. Verify before trusting the body.

Headers:

X-Vex-Signature: sha256=<hex hmac>
X-Vex-Timestamp: 1720531200

The signature is HMAC-SHA256(secret, "<timestamp>." + raw_body) using your webhook signing secret. Verify in Python:

import hashlib, hmac, time

def verify(request_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # 1. Reject stale deliveries (replay protection)
    if abs(time.time() - int(timestamp)) > 300:
        return False
    # 2. Recompute and compare in constant time
    signed = f"{timestamp}.".encode() + request_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Always verify

Reject any delivery that fails signature or timestamp checks. Use a constant-time comparison (hmac.compare_digest) and never log the signing secret.

Delivery & retries¶

Respond 2xx within 10 seconds to acknowledge.
Failed deliveries retry with exponential backoff for up to 24 hours.
Deliveries carry a stable X-Vex-Delivery id — deduplicate on it.

Inbound: CI Gate¶

Your pipeline can trigger a scan and receive a pass/fail verdict:

curl -sS -X POST https://<host>/api/v1/webhook/scan \
  -H "X-Vex-Key: <org-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://staging.example.com","fail_on":"high"}'

fail_on: critical | high | medium | never. The response verdict is pass or fail. Full walkthrough in CI Gate.