Webhooks & Events
Receive real-time HTTP callbacks when scans complete, compliance scores change, or critical security events occur in your ComplyWise account.
On this page
Webhooks Overview
Webhooks allow your systems to receive real-time notifications from ComplyWise. When an event occurs (scan completed, compliance score change, new finding), ComplyWise sends an HTTP POST request to your configured endpoint with event details as JSON. This enables integration with Slack, PagerDuty, Jira, and custom automation workflows.
- HTTP POST callbacks to your endpoint
- JSON payload with event type and details
- Configurable per event type
- Retry logic with exponential backoff on failure
Configuring Webhooks
Configure webhooks in Settings → Integrations → Webhooks or via the API. Each webhook subscription includes a target URL, a secret for signature verification, and the event types you want to receive. You can create multiple webhook subscriptions to send different event types to different endpoints.
- POST /api/webhooks — create: { "url": "https://your-endpoint.com/hook", "events": ["scan.completed"], "secret": "your-secret" }
- GET /api/webhooks — list all webhook subscriptions
- DELETE /api/webhooks/{id} — remove a webhook subscription
- Admin role required for webhook management
Event Types
ComplyWise emits events for key platform activities. Subscribe to specific event types or use the wildcard (*) to receive all events. Each event includes a type, timestamp, and event-specific payload.
- scan.completed — a scan job finished with results summary
- scan.failed — a scan job encountered an error
- compliance.score_changed — overall or framework compliance score changed
- compliance.control_failed — a previously passing control is now failing
- evidence.uploaded — new evidence artifact was uploaded
- integration.disconnected — an integration lost connectivity
Payload Format
Webhook payloads follow a consistent envelope format. Every payload includes an event type, event ID (for deduplication), timestamp, and a data object with event-specific details. The X-ComplyWise-Signature header contains a cryptographic signature of the payload body using your webhook secret.
- Envelope: { "event": "scan.completed", "event_id": "uuid", "timestamp": "ISO-8601", "data": { ... } }
- scan.completed data: { "scan_job_id": "uuid", "total_controls": 49, "passed": 38, "failed": 11, "score": 77.6 }
- compliance.control_failed data: { "control_id": "CC6.1", "framework": "SOC 2", "previous_status": "passed", "new_status": "failed" }
- Signature header: X-ComplyWise-Signature: sha256={hmac}
Verifying Signatures
Always verify the webhook signature to ensure the request came from ComplyWise. Compute a cryptographic hash of the raw request body using your webhook secret, then compare it to the value in the X-ComplyWise-Signature header. Reject requests with invalid signatures to prevent spoofing.
- Compute signature of request body using your webhook secret
- Compare to X-ComplyWise-Signature header value
- Use constant-time comparison to prevent timing attacks
- Reject requests with mismatched signatures
Retry Policy
If your endpoint returns a non-2xx status code or times out, ComplyWise retries the delivery. Retries follow an exponential backoff schedule. After multiple failed attempts, the event is marked as failed and appears in the webhook delivery log in Settings.
- Multiple retry attempts with exponential backoff
- Configurable timeout per delivery attempt
- Failed deliveries visible in Settings → Webhooks → Delivery Log
- Webhook subscriptions auto-disabled after repeated consecutive failures