docs/public_api_webhooks_spec.md

🔌 Public Integration API & Developer Webhooks Specification

The Collaborative Fraud Intelligence (CFI) Webhook Gateway enables core banking systems, payment processors, and case management suites to receive real-time cryptographically signed notifications for security events (ALERT_CREATED, CASE_RESOLVED, MODEL_PROMOTED, DRIFT_DETECTED).

All deliveries are protected by HMAC-SHA256 signature verification, pre-registration and pre-flight Anti-SSRF validation, and fail-closed DNS resolution defenses.

---

📌 1. Endpoint Overview

The Webhook Gateway exposes three REST endpoints mounted under /v1/webhooks:

Endpoint	Method	Purpose	Security Controls
/v1/webhooks/subscriptions	POST	Register a new webhook target for an institution	Upfront SSRF URL validation, HTTPS enforcement, secret key generation
/v1/webhooks/test-dispatch	POST	Trigger a test signed payload to registered webhooks	Real-time signature generation, DNS-rebinding re-validation
/v1/webhooks/verify	POST	Utility endpoint to verify webhook signature authenticity	Constant-time HMAC comparison (hmac.compare_digest)

---

📥 2. Request & Response Schemas

2.1 Register Webhook Subscription (POST /v1/webhooks/subscriptions)

Request Payload:

{
  "tenant_id": "bank_alpha",
  "target_url": "https://api.bank-alpha.com/webhooks/cfi",
  "events": [
    "ALERT_CREATED",
    "CASE_RESOLVED"
  ]
}

Response Payload (HTTP 200 OK):

{
  "subscription_id": "sub_a9f8b7c6",
  "tenant_id": "bank_alpha",
  "target_url": "https://api.bank-alpha.com/webhooks/cfi",
  "secret_key": "whsec_0123456789abcdef",
  "events": [
    "ALERT_CREATED",
    "CASE_RESOLVED"
  ]
}

Store the generated secret_key securely in your Key Management Vault (e.g., AWS KMS, HashiCorp Vault). The key is required to compute and verify the payload signature on every received webhook.

---

2.2 Trigger Test Dispatch (POST /v1/webhooks/test-dispatch)

Query Parameters:

• tenant_id: Target institution identifier (e.g. bank_alpha).
• event_type: Event category (e.g. ALERT_CREATED).

Response Payload (HTTP 200 OK):

{
  "dispatched_count": 1,
  "event_type": "ALERT_CREATED",
  "sample_signature": "sha256=a8f5f167f44f4964e6c998dee827110c..."
}

---

2.3 Verify Incoming Webhook (POST /v1/webhooks/verify)

Request Payload:

{
  "payload": {
    "test": true,
    "message": "CFI Simulator Webhook Dispatch Test",
    "sample_tx": "tx_test_1001"
  },
  "signature": "sha256=a8f5f167f44f4964e6c998dee827110c...",
  "secret_key": "whsec_0123456789abcdef"
}

Response Payload (HTTP 200 OK):

{
  "valid": true
}

---

📢 3. Supported Webhook Event Types

Event Type	Trigger Condition	Target Payload Content
ALERT_CREATED	A high-risk fraud anomaly exceeds the consortium threshold ($Score \ge 700$)	Anonymized transaction ID, risk score, triggered rule flags, and top feature attributions
CASE_RESOLVED	An investigation case is marked resolved by compliance analysts	Case ID, resolution outcome (CONFIRMED_FRAUD or FALSE_POSITIVE), and timestamp
MODEL_PROMOTED	A new global federated model surpasses champion benchmark metrics	Model version identifier, test PR-AUC, ROC-AUC, and timestamp
DRIFT_DETECTED	Data distribution shift auditor detects significant covariate or feature drift	Drifted feature names, Wasserstein distance ($W_1$), and JS-divergence metrics

---

🛡️ 4. Anti-SSRF Defense Specification

The webhook engine strictly validates target URLs against Server-Side Request Forgery (SSRF) during subscription registration and prior to payload transmission:

1. Protocol Restriction: Only http:// and https:// schemes are permitted; non-web protocols (file://, gopher://, ftp://) are rejected immediately.
2. Loopback & Localhost Blocking: 127.0.0.0/8, ::1, localhost, localhost.localdomain, and .local / .internal suffixes.
3. Cloud Metadata & Link-Local IP Blocking:
   • 169.254.169.254 (AWS IMDSv1/v2, Azure, GCP metadata service)
   • 169.254.0.0/16 (IPv4 Link-Local)
   • fe80::/10 (IPv6 Link-Local)
4. Private RFC 1918 Subnets:
   • 10.0.0.0/8
   • 172.16.0.0/12
   • 192.168.0.0/16
5. Reserved & Multicast Ranges: 224.0.0.0/4, 240.0.0.0/4, 0.0.0.0/8.
6. DNS Resolution Check: Resolves target hostnames via socket.getaddrinfo to identify hostnames resolving to internal or private addresses.
7. Fail-Closed Resolution Policy: If DNS resolution fails (socket.gaierror, socket.herror, OSError), the URL is rejected (False) to prevent unresolvable hostname SSRF bypasses.
8. Double-Check DNS Rebinding Defense: URL validation executes at registration time AND immediately before asynchronous delivery dispatch.

---

🔐 5. HMAC-SHA256 Signature Verification

Every outgoing HTTP POST request from the Webhook Gateway includes structured security headers:

POST /webhooks/cfi HTTP/1.1
Host: api.bank-alpha.com
User-Agent: CF-Intelligence-Webhook/1.0
Content-Type: application/json
X-CFI-Event-Id: evt_99882211
X-CFI-Event-Type: ALERT_CREATED
X-CFI-Signature-256: sha256=a8f5f167f44f4964e6c998dee827110c...
X-CFI-Timestamp: 2026-09-14T12:00:00.000000+00:00

{
  "event_id": "evt_99882211",
  "event_type": "ALERT_CREATED",
  "payload": {
    "transaction_id": "tx_88992211",
    "risk_score": 895,
    "decision": "BLOCK"
  }
}

5.1 Verification Logic (Receiver-Side Python Example)

import hmac
import hashlib

def verify_cfi_webhook(secret_key: str, payload_bytes: bytes, received_signature: str) -> bool:
    """Validate webhook payload HMAC-SHA256 signature in constant time.
    
    Args:
        secret_key: The subscription secret key (whsec_...) provided at registration.
        payload_bytes: The raw unparsed HTTP request body bytes.
        received_signature: Value from the X-CFI-Signature-256 header.
    
    Returns:
        True if the signature is valid, False otherwise.
    """
    expected_hex = hmac.new(
        secret_key.encode("utf-8"),
        payload_bytes,
        digestmod=hashlib.sha256,
    ).hexdigest()
    
    expected_signature = f"sha256={expected_hex}"
    
    # Constant-time comparison prevents timing side-channel attacks
    return hmac.compare_digest(expected_signature, received_signature)

Alternatively, partners can invoke WebhookService.verify_signature(payload_bytes, received_signature, secret_key) or call the API endpoint POST /v1/webhooks/verify.

---

⚡ 6. Asynchronous Delivery & SLA Semantics

• Strict Delivery Timeout: Outbound HTTP requests timeout after 3.0 seconds (httpx.AsyncClient(timeout=3.0)).
• Non-Blocking Execution: Webhook deliveries execute asynchronously without blocking the core payment scoring or transaction ingestion pipeline.
• Fail-Safe Logging: Delivery failures and HTTP non-2xx status codes log structured failure events for SIEM/audit ingestion without interrupting ongoing federated rounds.

---

🧪 7. Automated Test Verification Matrix

All developer webhook capabilities, cryptographic signing routines, and SSRF defenses are verified by continuous automated test suites:

Test Suite	File Path	Verified Capabilities	Status
Subscription Registration	backend/tests/unit/test_webhook_gateway.py	Registration, secret key generation (whsec_), event filtering	PASSED
HMAC-SHA256 Signature	backend/tests/unit/test_webhook_gateway.py	compute_hmac_signature, constant-time hmac.compare_digest	PASSED
SSRF Perimeter Defense	backend/tests/unit/test_webhook_gateway.py	Loopback, AWS metadata 169.254.169.254, RFC 1918, non-HTTP scheme rejection	PASSED
Fail-Closed DNS Validation	backend/tests/unit/test_webhook_gateway.py	socket.gaierror fail-closed rejection, DNS-rebinding double-check	PASSED
Verification Endpoint	backend/tests/unit/test_webhook_gateway.py	POST /v1/webhooks/verify companion receiver validation	PASSED
OpenAPI Contract Accuracy	backend/tests/unit/test_openapi_contract_accuracy.py	Schema parity across all mounted routes including /v1/webhooks	PASSED