Skip to main content
Event Name: related_party.kyc_session_created
This event is fired when the onboarding team creates a KYC verification session for a related party (Shareholder, UBO or Authorized Representative) of a business user. Use it to inform the related party — usually via email — that they need to complete the verification before the session expires. The session state at this point is always NOT_STARTED, which is reflected as KYC_PENDING on the related party.

Event Payload

The webhook payload contains the following structure:
Example Payload

Field Description

string
required
Unique event identifier (UUID).
string
required
Event type — always related_party.kyc_session_created for this webhook.
string
required
Event timestamp in ISO 8601 format.
object
required
Contains the event data.
object
required
Business user that the related party belongs to.
integer
required
Internal numeric identifier of the business user.
string
required
Legal name of the business user.
Related party for whom the KYC session was created.
Unique related party identifier (UUID).
Role of the related party within the business. Possible values: SHAREHOLDER, UBO, AUTHORIZED_REPRESENTATIVE.
Related party’s first name.
Related party’s last name.
Email address used to contact the related party for the verification.
Related party’s phone number, when available.
ISO 3166-1 alpha-2 country code of the related party’s nationality.
Percentage of the business owned by the related party. Omitted when not applicable (e.g. authorized representatives).
Residential address of the related party.
Street address line.
City.
Province or state.
Postal or ZIP code.
ISO 3166-1 alpha-2 country code.
KYC status of the related party at the time the session is created. Always KYC_PENDING for this event.
object
required
Newly created KYC session.
string
required
Unique KYC session identifier (UUID).
string
required
Identity verification provider. Currently mati.
string
required
Hosted URL the related party must visit to complete the verification.
string
ISO 8601 timestamp at which the session expires. May be omitted when the provider does not return an expiration.

Expected Responses

Success Response

HTTP 200 OKThe webhook was processed successfully.

Client Error

HTTP 4xx StatusClient-side error. Will not be retried.

Server Error

HTTP 5xx StatusServer-side error. Will be retried with exponential backoff.

Implementation Example