🔔

Upcoming Feature: Webhooks

Webhooks are scheduled for release in March 2026.
This documentation is provided in advance to help you prepare and accelerate your integration once the webhook system becomes available.

Webhooks enable your application to receive real-time notifications about events occurring in Kompliant. This document describes the structure of webhook notifications, how they are encrypted, and what data you can expect to receive.

Overview

When important events happen in Kompliant workflows—such as workflow completions, subject record updates, account provisioning operations, and more—Kompliant sends an HTTP POST request to your configured webhook endpoint with a JSON payload containing:

• Authenticated metadata about the event (readable but verified)
• Encrypted payload containing sensitive event-specific data

The encryption uses AES-256-GCM with your webhook key, ensuring that only your application can decrypt and read the event details.

Webhook notifications originate from a predefined allowed list of IP addresses. view full list

Quick Reference

Webhook Structure

When Kompliant sends a webhook to your endpoint, you'll receive a POST request with this JSON structure:

{
  "id": "wh_2K9mPxR7N4jL8hS6TdWfY3",
  "event_type": "WORKFLOW_COMPLETED",
  "timestamp": "2025-11-21T14:30:22.123Z",
  "account_id": "lv_4K8mPxR9N2jL7hS5TdWfY1",
  "schema_version": "2025-11-21",
  "key_id": "whk_20251121_01",
  "data": "AAAAAGTlm2L8V9x...encrypted_base64_payload...==",
  "retry_count": 0
}

Field Reference

Understanding Encryption Levels

Kompliant uses a dual-encryption strategy for webhook security:

Metadata Fields (Authenticated, Not Encrypted)

The envelope metadata fields (id, event_type, timestamp, etc.) are authenticated but not encrypted. This allows you to:

• Route incoming webhooks without decryption
• Log and monitor webhook events
• Check for duplicates using the webhook id

However, they are cryptographically verified during decryption. If any metadata is modified during transit, the GCM verification will fail and decryption will be rejected.

Encrypted Payload (Encrypted and Authenticated)

The data field contains sensitive information—such as personal identification numbers, bank account details, and business confidential data—and is fully encrypted and authenticated using AES-256-GCM with your webhook key.

This two-level approach gives you:

• Security: Sensitive data is encrypted using your shared secret
• Authenticity: Metadata cannot be tampered with without detection
• Routing efficiency: You can process and route webhooks before decryption

Webhook Events

Webhooks are triggered by various events in Kompliant workflows. The event type appears in the event_type field and determines what kind of data is contained in the encrypted payload.

Event types use an ALL_CAPS naming convention with underscores:

{RESOURCE}_{ACTION}

Examples:

• WORKFLOW_STARTED - A workflow has been initiated
• WORKFLOW_COMPLETED - A workflow has finished successfully
• SUBJECT_RECORD_DATA_UPDATED - Entity data has been modified

Your webhook integration should be prepared to handle multiple event types, as Kompliant may add new event types over time.

For detailed information about available event types and their payload structures, see:

• Webhook Events Payloads - Understanding payload versioning
• Webhook Structure - Version 1.0 - All available event types and schemas

Encryption and Authentication Flow

Kompliant uses AES-256-GCM (Galois/Counter Mode) encryption, which provides both encryption and authentication in a single operation. Here's how it works:

How the Encryption Works

1. Metadata as Additional Authenticated Data (AAD)

   • The webhook metadata (id, event_type, timestamp, account_id, schema_version, key_id) is used as "additional authenticated data"
   • This data is not encrypted but is cryptographically bound to the encrypted payload
   • Attempting to modify metadata without the key will cause decryption to fail

2. Payload Encryption

   • Your actual event data (in the data field) is encrypted using AES-256-GCM
   • Uses the shared secret associated with the key_id as the encryption key
   • Produces an authentication tag that covers both the encrypted data and the metadata

3. Decryption Verification

   • When you decrypt, you provide the metadata as AAD
   • GCM verifies that the metadata hasn't been modified
   • If verification fails, decryption returns an error (don't trust the payload)

Practical Impact

This approach means:

• ✅ You can trust the metadata fields (event_type, timestamp, key_id, etc.)
• ✅ You cannot decrypt if metadata is modified
• ✅ Accidental bit flips or corruption is caught
• ✅ Malicious tampering is detected

Decrypted Payload Versioning

After decrypting the data field using your webhook key, you'll receive event-specific JSON with its own version field:

{
  "version": "1.0",
  "subject_record_id": "sr_6N48sDzY7ysrBFJIS4TtuD",
  ...
}

The version field within the decrypted payload indicates the structure of the event data. Currently this is 1.0.

Important: The decrypted payload structure varies by event type. For complete payload schemas and available event types, see:

• Webhook Events Payloads - Versioning strategy
• Webhook Structure - Version 1.0 - Event schemas and examples

Setting Up Webhooks

To receive webhooks from Kompliant, you need to:

1. Create an encryption key using the webhook.key.create endpoint
2. Store the shared secret securely in your infrastructure
3. Activate the key using the webhook.key.activate endpoint
4. Configure webhook endpoints in Kompliant with your HTTPS URL

For detailed setup instructions, see the Webhook Integration Guide.

Key Management

Webhook keys can be rotated:

1. Create a new key (status: INACTIVE)
2. Update your application to handle the new key (add to your key mapping)
3. Activate the new key
4. Kompliant will use the new key for future webhooks
5. Previous key remains valid for webhooks already in transit

For full setup details including how to securely store shared secrets, refer to Webhook Integration Guide.

Webhook Delivery Guarantees

Kompliant implements an at-least-once delivery model for webhooks:

Delivery Behavior

• Webhooks are delivered via HTTP POST to your configured HTTPS endpoint
• Your endpoint has 30 seconds to return HTTP 200 status
• If you don't respond with HTTP 200 within 30 seconds, the webhook is considered failed

Retry Strategy

Failed webhooks are retried with exponential backoff:

After 95 failed delivery attempts, the webhook is archived and no longer retried.

Duplicate Handling

Because webhooks may be delivered multiple times, you should implement idempotent processing:

• Use the webhook id field to detect duplicates
• Store processed webhook IDs in your database
• Skip processing if you've already handled this id

This prevents accidentally processing the same event twice if a webhook is retried.

Best Practices for Reliable Delivery

1. Fast Response: Return HTTP 200 immediately after validating the webhook structure, before processing
2. Async Processing: Queue the event for background processing rather than handling it synchronously
3. Deduplication: Always check the webhook id before processing
4. Error Handling: Only return HTTP 200 if the webhook was safely stored or queued; return 5XX if you can't process it
5. Logging: Log received webhooks (safely, with secrets masked) for debugging delivery issues

Webhook Encryption Key Management

⚠️

Important: Contact Kompliant Team

If you lose your shared secret, cannot decrypt webhooks, need to rotate keys immediately, or have questions about webhook security, please contact the Kompliant support team immediately. They can help you manage keys, troubleshoot decryption issues, and ensure your integration stays secure.

Shared Secret Security

Your shared secret (returned during key creation) is sensitive information equivalent to an API key or password:

• Only returned once during key creation
• Never stored by Kompliant after creation
• Your responsibility to secure it in your infrastructure
• If compromised, create a new key and rotate immediately

Recommended Secret Storage

• Cloud Secrets Manager: AWS Secrets Manager, Azure Key Vault, Google Secret Manager
• Environment Variables: For containerized applications with secure injection
• Hardware Security Modules (HSM): For enterprise security requirements
• Encrypted Configuration: Config files encrypted at rest with strict access controls

Never store shared secrets in:

• Version control systems (Git)
• Plain text files
• Client-side storage (browser, mobile)
• Log files or debugging output
• Unencrypted databases

Versioning

Webhook versioning allows Kompliant to evolve the webhook format over time while maintaining backward compatibility.

Schema Version

The schema_version field in the webhook envelope indicates the structure of the metadata fields. Currently, this is 2025-11-21, which describes the webhook envelope format shown in this document.

If Kompliant makes breaking changes to the envelope structure, a new schema version will be introduced. Your application should check this field and handle different versions if needed.

Payload Version

The version field within the decrypted payload indicates the structure of the event data itself. Currently this is 1.0.

As Kompliant adds new fields or changes event structures, new payload versions may be introduced. You should check this field when processing decrypted payloads to ensure you're handling the correct data structure.

For details on payload versioning and available event types, see Webhook Events Payloads.

Future Compatibility

In the future, you may be able to configure which webhook versions you want to receive on a per-endpoint basis, allowing gradual migration to new webhook formats.

Next Steps

• Structure & Event Types: See Webhook Structure - Version 1.0 for all available event types and payload schemas
• Getting Started: See the Webhook Integration Guide for setup instructions
• Receiving Webhooks: Read Receiving and Decrypting Webhooks for implementation examples
• • API Reference: Check the webhooks key and configuration endpoints