Webhooks & Event Streams

Webhooks provide an event-driven mechanism to notify external systems—such as GRC software, Jira, ServiceNow, or SIEM tools—immediately when specific actions occur within AIIA.

Rather than continuously polling the REST API for updates, external systems can register an HTTP POST endpoint to receive JSON payloads in real-time.

---

Supported Event Types

AIIA triggers webhooks for the following system events:

Event Type	Description	Typical Use Case
finding.created	Triggered when a new audit finding is drafted.	Notify management or seed GRC databases.
finding.status_changed	Triggered when a finding moves states (e.g., Management Response → Follow-Up).	Sync ticket status in Jira or ServiceNow.
action_plan.overdue	Triggered when a remediation action plan misses its deadline.	Alert control owners and escalate.
kri.breached	Triggered when a Key Risk Indicator crosses a configured threshold.	Dispatch alerts to SIEM or security operations teams.
report.approved	Triggered when an audit report receives official sign-off.	Archive final PDF in document repositories.

---

Payload Schema Example

Webhooks are delivered as an HTTP POST request with a JSON body. Below is an example payload for a finding.status_changed event:

{
  "event_id": "evt_9a2f1c8d4e7b",
  "event_type": "finding.status_changed",
  "timestamp": "2026-05-24T12:30:15Z",
  "org_id": 1,
  "data": {
    "finding_id": 402,
    "title": "Unauthorized Database Access Logs Enabled",
    "severity": "High",
    "old_status": "ManagementResponse",
    "new_status": "Final",
    "assigned_to": "fatimah.mgr",
    "remediation_deadline": "2026-07-24"
  }
}

---

Webhook Signature Verification

To guarantee that incoming webhooks originate from your AIIA instance and have not been modified in transit, you should verify the cryptographic signature included in the headers of all webhook deliveries.

Each webhook request contains an X-AIIA-Signature header computed as a keyed-hash message authentication code (HMAC) using the SHA-256 algorithm and your webhook's secret key.

Header Format

X-AIIA-Signature: t=1779660218,v1=9e8f7a6c5b4d3e2f1a...

• t is the timestamp of the event delivery (used to prevent replay attacks).
• v1 is the actual HMAC-SHA256 signature hash of the request body.

Signature Validation Code (Python)

import hmac
import hashlib
import time

def verify_webhook(payload_body: bytes, signature_header: str, secret_key: bytes) -> bool:
    # Parse header components
    parts = dict(item.split('=') for item in signature_header.split(','))
    timestamp = parts.get('t')
    received_signature = parts.get('v1')
    
    # 1. Prevent replay attacks (reject payloads > 5 minutes old)
    if abs(time.time() - int(timestamp)) > 300:
        return False
        
    # 2. Re-create the signature payload string
    # Format: timestamp.body
    signature_payload = f"{timestamp}.".encode('utf-8') + payload_body
    
    # 3. Compute expected signature
    computed_signature = hmac.new(
        secret_key,
        signature_payload,
        hashlib.sha256
    ).hexdigest()
    
    # 4. Secure constant-time comparison
    return hmac.compare_digest(computed_signature, received_signature)

---

Delivery Failures & Retry Policy

AIIA guarantees at-least-once delivery for all registered webhooks. If the target server responds with a non-2xx status code or times out:

1. Immediate Retry: The worker schedules a retry after 60 seconds.
2. Exponential Backoff: If the second attempt fails, AIIA will retry up to 5 times using an exponential backoff strategy (1m, 5m, 15m, 1h, 4h).
3. Deactivation: If a webhook fails consistently for 72 hours, its status is updated to Inactive (inactive), and an alert notification is dispatched to administrators.