This integration pattern guides you through the complete process of setting up and managing webhook encryption keys in your Kompliant integration.

📘

New to Webhooks?

Start with Webhook Notifications to understand the webhook structure, payload format, and encryption model before setting up keys.

Overview

Webhooks in Kompliant provide real-time notifications about events in your workflows and applications. To ensure security, all webhook payloads are encrypted using AES-256-GCM encryption with a shared secret that only you and Kompliant know.

This guide covers the key setup and management workflow. For complete webhook structure and format details, see Webhook Notifications.

The webhook setup workflow involves:

1. Create a webhook encryption key
2. Securely store the shared secret
3. Activate the key to start receiving webhooks
4. (Optional) Rotate keys for enhanced security

This guide walks you through each step to get your webhook integration operational.

Setup Requirements

⚠️

Important: Contact Kompliant Team

Webhook configuration requires setup by the Kompliant team. You cannot configure webhooks through the API or dashboard directly.

To set up webhooks for your account:

1. Contact your Kompliant representative or support team
2. Provide your webhook endpoint URL
3. Specify which event types you want to receive
4. Confirm your endpoint is ready to receive POST requests

The Kompliant team will configure your webhook settings and confirm when setup is complete.

Step 1: Create a Webhook Encryption Key

The first step is to create a new webhook encryption key using the webhook.key.create endpoint. This generates a SharedSecret that will be used to encrypt webhook payloads.

When you call this endpoint with your account_id, you'll receive:

• key_id: The identifier for the new key (format: whk_YYYYMMDD_NN)
• shared_secret: The base64-encoded encryption key
• status: Will be INACTIVE for newly created keys
• created_at: Timestamp of key creation

⚠️

Critical: Store the Shared Secret Immediately

The shared_secret is only returned once during key creation. You must store it securely in your infrastructure immediately. If you lose it, you'll need to create a new key.

📘

Your Account ID

Your account ID is provided when you receive your API credentials. It typically starts with lv_ or sb_.

Understanding Key IDs

Key IDs follow the format whk_YYYYMMDD_NN where:

• whk_ is the webhook key prefix
• YYYYMMDD is the creation date (e.g., 20251021 for October 21, 2025)
• NN is the iteration number (01-99)

This format supports key rotation - you can create multiple keys and switch between them without downtime.

Step 2: Securely Store the Shared Secret

Before activating your key, you must store the shared secret in your infrastructure's secure storage system.

Best Practices for Storage

✅ Recommended Approaches:

• Secrets Manager: AWS Secrets Manager, Azure Key Vault, Google Secret Manager
• Environment Variables: For containerized applications with secure variable injection
• Hardware Security Modules (HSM): For enterprise-grade security requirements
• Encrypted Configuration: Encrypted config files with restricted access

❌ Avoid These Approaches:

• Plain text files in your codebase
• Version control systems (Git, SVN, etc.)
• Unencrypted databases
• Client-side storage (browser localStorage, cookies)
• Log files or debugging output

Implementation Example

Create a mapping between key_id and the shared_secret in your system:

// Example: Node.js with environment variables
const WEBHOOK_KEYS = {
  'whk_20251021_01': process.env.WEBHOOK_SECRET_20251021_01,
  'whk_20251021_02': process.env.WEBHOOK_SECRET_20251021_02
};

function getSharedSecret(keyId) {
  const secret = WEBHOOK_KEYS[keyId];
  if (!secret) {
    throw new Error(`Unknown webhook key: ${keyId}`);
  }
  return secret;
}

# Example: Python with secrets management
import boto3
import json

def get_shared_secret(key_id):
    """Retrieve shared secret from AWS Secrets Manager"""
    secrets_client = boto3.client('secretsmanager')

    try:
        response = secrets_client.get_secret_value(
            SecretId=f'kompliant/webhook/{key_id}'
        )
        return response['SecretString']
    except Exception as e:
        raise ValueError(f"Failed to retrieve secret for {key_id}: {e}")

Step 3: Activate the Webhook Key

Once you've securely stored the shared secret and tested your decryption implementation (see Receiving and Decrypting Webhooks), you can activate the key using the webhook.key.activate endpoint.

Call this endpoint with the key_id you want to activate. The response will confirm:

• The key is now ACTIVE
• The timestamp when it was activated

📘

What Happens During Activation

• The specified key changes from INACTIVE to ACTIVE
• Any previously ACTIVE key is automatically moved to DELETED status
• All new webhooks will use the newly activated key
• Only one key can be ACTIVE at a time per account

Key Rotation (Best Practice)

Regular key rotation enhances security by limiting the lifespan of any single encryption key. Here's the recommended rotation workflow:

Step-by-Step Rotation Process

1. Generate a New Key

Call webhook.key.create to generate a new encryption key. You'll receive a new key_id (e.g., whk_20251021_02) and the corresponding shared_secret.

2. Update Your System

• Store the new shared secret in your secrets management system
• Update your webhook handler to recognize the new key_id
• Deploy the changes to your production environment
• Test with the new key (optional but recommended)

3. Activate the New Key

Call webhook.key.activate with the new key_id to make it active.

4. Results After Activation

✅

Zero Downtime

This rotation process ensures zero downtime. Your webhook handler can recognize multiple keys, and the transition happens atomically when you activate the new key.

Rotation Frequency Recommendations

• Standard Security: Rotate every 90 days
• Enhanced Security: Rotate every 30 days
• After Security Incident: Rotate immediately
• Team Member Departure: Rotate if they had access to secrets

Verifying Key Status

You can check the status of any webhook key at any time using the webhook.key.get endpoint.

Provide a key_id and you'll receive:

• Current status (INACTIVE, ACTIVE, or DELETED)
• Creation timestamp
• Activation timestamp (if activated)
• Deletion timestamp (if deleted)

📘

Shared Secret Not Returned

For security reasons, the shared_secret is never returned by this endpoint. It's only provided once during key creation.

Key Status Reference

For more information on key statuses, see WEBHOOK_KEY_STATUSES.

Common Issues and Solutions

Issue: Lost Shared Secret

Problem: You didn't store the shared secret after creation.

Solution: Create a new webhook key and follow the proper storage steps before activation.

Issue: Daily Key Limit Reached

Problem: You've created 100 keys in a single day.

Error Response:

{
  "meta": {
    "status": "ERROR",
    "version": "2025-03-24"
  },
  "errors": [{
    "code": "SYSTEM_RULE_VIOLATION",
    "message": "Maximum daily key creation limit reached",
    "entity_type": "Webhook Key",
    "sub_code": "DAILY_KEY_LIMIT"
  }]
}

Solution: Wait until the next day or contact support if you have a legitimate need for more keys.

Issue: Cannot Activate Deleted Key

Problem: Trying to activate a key that was previously deleted.

Solution: Create a new key instead. Once a key is deleted, it cannot be reactivated.

Next Steps

Now that you've set up your webhook encryption keys, you're ready to:

1. Understand webhook structure - See Webhook Notifications for details on what you'll receive
2. Configure your webhook endpoint to receive POST requests from Kompliant
3. Implement webhook decryption in your application - See Receiving and Decrypting Webhooks for implementation examples
4. Handle webhook events based on your business logic
5. Monitor webhook delivery and implement retry logic for failures

For a complete guide on receiving and processing webhooks, see Receiving and Decrypting Webhooks.