Skip to main content
Version: 1.0.0-beta

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:
FieldDescription
NameDescriptive name for the webhook
URLHTTPS endpoint to receive events
SecretShared secret for HMAC signature verification
EventsSelect which events trigger the webhook
ActiveEnable/disable the webhook

Event Types​

Engagement Events​

EventTriggered When
engagement.createdNew engagement created
engagement.status_changedEngagement status changes
engagement.closedEngagement is closed

Finding Events​

EventTriggered When
finding.createdNew finding documented
finding.severity_changedFinding severity changes
finding.closedFinding is closed

KRI Events​

EventTriggered When
kri.alert_triggeredKRI threshold breached
kri.alert_resolvedAlert condition resolved

Approval Events​

EventTriggered When
report.approvedReport receives approval
signoff.completedWorkpaper sign-off completed

PBC Events​

EventTriggered When
pbc.item_submittedClient submits a requested item
pbc.request_overduePBC 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.