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

📘

Prerequisites

Before configuring endpoints, you need an active webhook encryption key. See Webhook Integration Guide to complete that setup first.

Overview

Webhook configurations define the destination URLs for webhook delivery. Each configuration is an HTTPS endpoint registered to your account and identified by a whc_-prefixed ID. Webhook payloads are delivered to all active configurations simultaneously.

The endpoint configuration workflow involves:

1. Create one or more webhook endpoint configurations
2. Verify your configurations are active
3. (Optional) Update an endpoint URL as your infrastructure changes
4. (Optional) Delete configurations you no longer need

Each account supports up to 20 active configurations.

Step 1: Create a Webhook Endpoint Configuration

Register an HTTPS endpoint using the webhook.config.create endpoint. See the full request/response reference for parameter details.

Provide your account_id and the destination url. Store the returned config_id — you'll need it to get, update, or delete this configuration later.

⚠️

URL Requirements

• The URL must start with https:// — plain HTTP is rejected
• Each URL must be unique per account — registering the same URL twice returns a URL_ALREADY_EXISTS error
• URLs are case-sensitive

Understanding Config IDs

Config IDs use the format whc_ followed by a random alphanumeric string (e.g., whc_2K9mPxR7N4jL8hS6TdWfY3). Each ID uniquely identifies a single endpoint configuration for an account.

Step 2: Verify Your Configurations

After creating one or more endpoints, use webhook.config.list to confirm what is registered for your account. See the full request/response reference for details.

The list only includes active configurations — deleted ones are excluded. If no configurations exist, configs returns as an empty array.

You can also retrieve a specific configuration at any time using webhook.config.get with its config_id.

📘

updated_at on New Configurations

For newly created configurations that have never been updated, updated_at reflects the creation time.

Updating an Endpoint URL

If your endpoint URL changes, use webhook.config.update to update it in place — no need to delete and recreate. See the full request/response reference for details.

The new URL must be unique for your account — you cannot update to a URL already registered under another configuration.

⚠️

Deleted Configs Cannot Be Updated

Calling update on a deleted configuration returns ENTITY_NOT_FOUND. Create a new configuration instead.

Deleting a Configuration

Remove a configuration you no longer need using webhook.config.delete See the full request/response reference for details.

⚠️

Deletion is Permanent

Deleted configurations cannot be restored. The endpoint immediately stops receiving deliveries. If you need to temporarily pause deliveries, consider rotating your webhook key instead of deleting the endpoint configuration.

Configuration Limits

Each account can have a maximum of 20 active configurations. This limit applies to non-deleted configurations only — deleted configs do not count toward the limit.

If you reach the limit, you'll receive a SYSTEM_RULE_VIOLATION / MAX_WEBHOOK_URL_LIMIT error — see webhook.config.create for the full error reference. Delete unused configurations with webhook.config.delete to free up capacity before creating new ones.

Configuration Status Reference

Common Issues and Solutions

Issue: URL Already Registered

Problem: Attempting to create or update to a URL that is already registered for your account. Returns a SYSTEM_RULE_VIOLATION / URL_ALREADY_EXISTS error — see webhook.config.create for the full error reference.

Solution: Use webhook.config.list to find the existing configuration for that URL. Update or delete it as needed, or use a different URL.

Issue: Configuration Not Found

Problem: A config_id returns ENTITY_NOT_FOUND.

Possible causes:

• The config_id belongs to a different account_id
• The configuration was previously deleted
• The config_id format is invalid (must start with whc_)

Solution: Use webhook.config.list to retrieve valid config_id values for your account.

Issue: Reached the 20-Config Limit

Problem: You cannot create new configurations.

Solution: Call webhook.config.list to review all active configurations, identify ones that are no longer in use, and delete them with webhook.config.delete.

Next Steps

With your endpoint configured, you're ready to:

1. Activate your webhook key — See Webhook Integration Guide if you haven't activated a key yet
2. Implement decryption in your endpoint handler — See Receiving and Decrypting Webhooks for implementation examples
3. Handle webhook events — See Webhook Notifications for the full payload structure and event types
4. Monitor delivery — Use webhook.config.list to audit your active endpoints at any time