Webhooks/Callbacks

We are expanding our callback system to give integrators more flexibility.

Currently, our platform sends REST callbacks primarily for customer and contract acceptance events. With this update, callbacks can optionally use a topic-based structure that mirrors our existing WebSocket messages.

Existing REST Callback Structure

Current callbacks are lightweight JSON arrays with minimal data about accepted customers or contracts as described here:

[
  {
    "status": 100,
    "key": "f283d8c84766484892cf097db8c5e2b5",
    "modified": "2025-09-03T06:38:08",
    "customerKey": "885eb2cc-12d6-49dd-b52a-a6634f510e17"
  }
]

or

[
  {
    "status": 100,
    "key": "f283d8c84766484892cf097db8c5e2b5",
    "modified": "2025-09-03T06:38:08",
    "contractKey": "885eb2cc-12d6-49dd-b52a-a6634f510e17"
  }
]

Field	Type	Description
status	number	Processing status (e.g., 100 = accepted)
key	string	Internal record key for the event
modified	string	ISO 8601 timestamp of the last modification
customerKey	string	(Optional) UUID identifying the customer
contractKey	string	(Optional) UUID identifying the contract

New Optional Topic-Based Callback Structure

The new callback format is optional and provides a more structured and extensible payload.

Each message contains a topic field to indicate the event type and its corresponding data payload.

[
  {
    "topic": "complianceRecord",
    "complianceRecord": [
      {
        "status": 100,
        "key": "ac0a1122ad4c440db62fe3eb602d8941",
        "modified": "2025-09-03T06:36:49",
        "customerKey": "92561303-8e1d-4b71-9537-d7c8d6163ccc"
      }
    ]
  }
]

Field	Type	Description
topic	string	Event topic (e.g., complianceRecord, identResult, etc.)
complianceRecord	array	Array of compliance record objects for this event
status	number	Processing status of the record
key	string	Internal record key
modified	string	ISO 8601 timestamp of the last modification
customerKey	string	UUID identifying the customer

Example with Additional Topics

The new model can include multiple event topics in a single callback, mirroring our WebSocket events:

[
  {
    "topic": "identResult",
    "kyc": "WEBID",
    "identId": "315065706",
    "personKey": "0ac7e1d8-9e39-486b-b28d-bd8551ec90ed",
    "reason": null,
    "status": "success"
  }
]

Field	Type	Description
topic	string	Event topic (identResult)
kyc	string	KYC provider name (e.g., WEBID)
identId	string	Identifier for the identification process
personKey	string	UUID for the identified person
reason	string or null	Reason for failure (if applicable)
status	string	Status of the identification (success, etc.)

Key Points

• Backward compatibility: Existing REST callbacks remain unchanged and supported.

• Optional enhancement: The new topic-based structure is opt-in and provides richer event data.

• WebSocket parity: REST callbacks now carry the same topics and payloads as WebSocket messages.

• Flexible integration: Choose between WebSockets, classic REST callbacks, or the new topic-based callbacks.