Webhook Structure: Version 1.0

This document describes the common payload structure for all webhook events in version 1.0. Each event type includes these standard attributes plus event-specific data.

Default Parameters

All webhook event payloads (version 1.0) include these standard fields after decryption:

Parameter	Type	Required	Description
version	string	Yes	The payload data version. Always `1.0` for this version.
subject_record_id	string	Yes	The Subject Record identifier associated with this event (format: `sr_XXXXX...`).
user_context	object	Yes	The user_context parameter defined in the table below.
workflow_id	string	No	The Workflow identifier if this event is associated with a workflow (format: `w_XXXXX...`). Present for workflow-based events.
workflow_type	string	No	One of WORKFLOW_TYPES .

User Context

The user_context object identifies who or what triggered the event that generated this webhook notification.

Parameter	Type	Required	Description
user_id	string	Yes	The identifier of the user or system that triggered the event. Can be an email address (for `USER` type), API key name (for `API_KEY` type), or `SYSTEM` (for automated system actions).
user_type	string	Yes	The type of user or actor. Must be one of: `USER` (human user identified by email), `API_KEY` (automated action via API key), or `SYSTEM` (automated Kompliant system action without specific user context like scheduled jobs or triggers).

User Context Combinations:

Human User: When a person performs an action through the UI
- user_id: User's email address (e.g., [email protected])
- user_type: USER
API Key: When an automated system uses an API key
- user_id: API key name (e.g., USER API Key 2025-06-05)
- user_type: API_KEY
System: When Kompliant's internal systems trigger an action
- user_id: SYSTEM
- user_type: SYSTEM
- Examples: Scheduled jobs, automatic provisioning operations, document generation

Event-Specific Attributes

Each event type includes additional attributes beyond these common fields. Refer to the individual event documentation for complete details:

Workflow Events

WORKFLOW_CREATED - Workflow creation notification
WORKFLOW_STARTED - Workflow processing has begun
WORKFLOW_COMPLETED - Workflow has finished

Subject Record Events

SUBJECT_RECORD_DATA_UPDATED - Entity data modifications
SUBJECT_RECORD_UNDERWRITING_STATUS_UPDATED - Underwriting decision changes

Verification Events

VERIFICATION_STATUS_UPDATED - Verification check status changes

Account Provisioning Events

MBTRUST_SUCCESS - Successful MBTrust provisioning
MBTRUST_FAILURE - Failed MBTrust provisioning
PROPAY_SUCCESS - Successful ProPay provisioning
PROPAY_FAILURE - Failed ProPay provisioning

Decision Document Events

DECISION_DOCUMENT_GENERATED - Underwriting decision document created

External System Events

HEARTLAND_CREDENTIALS_RECEIVED - Payment processor credentials available

Encryption Reminder

Important: The payloads shown in this documentation are decrypted for readability. When you receive webhook notifications at your endpoint, the data field will be encrypted using AES-256-GCM with your active webhook key.

To decrypt incoming webhooks:

Use the key_id from the webhook envelope to identify the correct SharedSecret
Retrieve your stored SharedSecret (from webhook.key.create)
Decrypt the data field using AES-256-GCM
Parse the decrypted JSON to access the payload structure described in this documentation

Refer to the webhook integration guide for implementation examples and code samples.

Next Steps

Choose an event type above to see detailed payload schemas and examples
Webhook Events Payloads - Understanding versioning
Webhook Integration Guide - Complete integration walkthrough