Webhook Reference

Webhooks enable real-time push notifications from AIIA to your systems. When events occur (finding created, report approved, KRI alert triggered), AIIA sends an HTTP POST to your configured endpoint.

Configuring Webhooks

1. Navigate to Administration → Integrations → Webhooks
2. Click + New Webhook
3. Enter:

Field	Description
Name	Descriptive name for the webhook
URL	HTTPS endpoint to receive events
Secret	Shared secret for HMAC signature verification
Events	Select which events trigger the webhook
Active	Enable/disable the webhook

Event Types

Engagement Events

Event	Triggered When
engagement.created	New engagement created
engagement.status_changed	Engagement status changes
engagement.closed	Engagement is closed

Finding Events

Event	Triggered When
finding.created	New finding documented
finding.severity_changed	Finding severity changes
finding.closed	Finding is closed

KRI Events

Event	Triggered When
kri.alert_triggered	KRI threshold breached
kri.alert_resolved	Alert condition resolved

Approval Events

Event	Triggered When
report.approved	Report receives approval
signoff.completed	Workpaper sign-off completed

PBC Events

Event	Triggered When
pbc.item_submitted	Client submits a requested item
pbc.request_overdue	PBC request passes due date

Payload Format

{
  "event": "finding.created",
  "timestamp": "2027-01-15T14:30:00Z",
  "data": {
    "id": 42,
    "title": "Unauthorized Access to Production Database",
    "severity": "CRITICAL",
    "engagement_id": 7,
    "created_by": "sarah.chen"
  },
  "webhook_id": "wh_abc123"
}

Security

• All webhook payloads are signed with HMAC-SHA256
• Verify the X-AIIA-Signature header against the shared secret
• Only HTTPS endpoints are supported
• Failed deliveries are retried up to 3 times with exponential backoff

Permissions

Webhook configuration requires Admin role.