Documentation
kompliant.com

Webhook Events & Paylods

Suggest Edits

Webhook event payloads are versioned to ensure your integrations remain stable as the Kompliant API evolves. The payload structure inside the encrypted data field uses semantic versioning to help you manage changes over time.

Payload Versioning

Each webhook notification includes a version field within the decrypted data payload. This version number indicates the structure and fields included in the event data.

Current Payload Versions:

  • Version 1.0 - Initial release (March 2026)

Version Format

Payload versions follow a semantic versioning format: MAJOR.MINOR

  • MAJOR version changes when we make incompatible changes that may break existing integrations
  • MINOR version changes when we add functionality in a backward-compatible manner

Encryption Notice

Important: When you receive webhook notifications, the data field will be encrypted using AES-256-GCM encryption with your active webhook key. All payload examples in this documentation show the decrypted structure for clarity.

To work with webhook payloads:

  1. Decrypt the data field using your SharedSecret (obtained from webhook.key.create)
  2. Parse the decrypted JSON
  3. Check the version field to determine the payload structure
  4. Process the event according to its version-specific schema

Envelope vs. Payload Versioning

Kompliant uses two separate version systems:

  1. Envelope Schema Version - Controls the top-level webhook structure (id, event_type, timestamp, etc.)

    • Indicated by the schema_version field in the webhook envelope
    • Current envelope version: 2025-11-21

  2. Payload Data Version - Controls the structure inside the encrypted data field

    • Indicated by the version field within the decrypted payload
    • Current payload version: 1.0

This dual versioning allows us to evolve the webhook infrastructure independently from the event data structure.

Version-Specific Documentation

For detailed information about the event types and payload structures available in each version, refer to the version-specific documentation:

Backward Compatibility

We are committed to maintaining backward compatibility within major versions. When we add new fields or event types, they will be introduced as minor version updates that won't break existing integrations.

If we need to make breaking changes, we will:

  1. Release a new major version
  2. Provide migration guides
  3. Support the previous version for a transition period
  4. Give advance notice before deprecating older versions

Next Steps

Updated 28 days ago