Onboarding Webhooks - Account and Profile Updates

Webhook Notifications Overview

Webhook notifications provide updates on key events related to account creation and onboarding progress. Below is a summary of the key notification types, implementation guidelines, and best practices.

Notification Types

1. Account Creation & Status Updates

Receive updates when an account is created or its status changes. Only when an account status is "Accepted" is a wallet created.

• Webhook Event ID: 50
• Status values

• Payload Example

{
	"EventDate": "2025-04-15T13:45:33.479Z",
	"AccountID": "37373",
	"ProfileID": "93843",
	"IntId" : "557949", 
	"ExtId": "2268ABBB-D26E-484C-8025-1BB2UATbyANP",
	"Status": "2",
	"NotifDate" : "2025-04-15T15:45:33.558",
  "NotifCategory" : "50"
}

2. Onboarding Progress Updates (Profile Statuses)

Track an end-user's onboarding journey through changes in profile status.

• Webhook Event ID: 49

• Status Values

  Notification Status	Profile Status	Status Trigger	Description
  1	CREATION_IN_PROGRESS	Callback after POST/account for an individual user	Onboarding is not required.
  1	AWAITING_INFORMATION	Callback after POST/account for a Business Relationship	Additional data and documents must be collected via an onboarding form.
  2	UNDER_ANALYSIS	Updated when onboarding is submitted.	The end-user has submitted the online onboarding. Lemonway’s analysts will now assess the information and decide whether to approve the account.
  3	ACCEPTED	Lemonway sends if an account status = accepted	Lemonway has accepted the entry into relationship. Account status switches to accepted and onboarding is over. Note: For a Legal Representative of an accepted Legal Entity, an ACCEPTED account status does not confirm individual KYC completion or wallet opening. For this status, you must check the individual profile status instead.
  4	DENIED	Lemonway sends if an account status = denied	Lemonway has denied the entry into relationship. Account status switches to denied and onboarding is over.
  5	REJECTED	Lemonway returns account status = rejected with one of the following reasons: Regulatory requirements not met. Onboarding request rejected. Onboarding process incomplete.	To finalise the onboarding process, we require further information from the end-user.

  Statues with no notification number

  Profile Status	Status Trigger	Description
  INFORMATION_COLLECTION_IN_PROGRESS	Update after a post/onboarding for a Business Relationship	Now that an onboarding form has been created, the end-user should complete their data and documents in Lemonway.
  IDENTITY_VERIFICATION_IN_PROGRESS	Update after an identity verification progress is launched	End-user must complete their id verification.
  IDENTITY_VERIFICATION_ABANDONED	End-user stopped during its process that timed-out	End-user needs to reopen their online onboarding to complete profile.
  IDENTITY_VERIFICATION_ERROR	Technical error during process	End-user needs to reopen its online onboarding to complete profile.

• Payload Example:

{
	"EventDate": "2025-04-15T09:19:09.430Z",
	"AccountID": "37373",
	"ProfileID": "454545",
	"IntId": "32",
	"ExtId": "jdkc",
	"Status": "2",
	"NotifDate" : "2025-04-15T11:19:09.559",
  "NotifCategory" : "49"
}

Description

3. Wallet Status Notification

This notification is sent when the status of a wallet changes.

• Webhook Event ID: 52
• Payload example - GET/accounts to retrieve the profileId

{
            "id": "c785b6bb-cf3b-46b3-bf05-57ab5ce424dc",
            "onboardingId": null,
            "identity": {
                "name": "Walter - Toy",
                "type": "COMPANY",
                "registrationNumber": "50JoRegistrationDOUBLON",
                "registrationCountry": "FR",
                "registrationDate": "1992-03-21"
            },
            "status": "ACCEPTED",
            "profiles": [
                {
                    "id": "7463b0a1-ed13-4666-b756-8f291f68d4b4",
                    "type": "PROJECT_HOLDER",
                    "status": {
                        "type": "ACCEPTED",
                        "subStatus": null
                    },
                    "wallets": [
                        {
                            "id": "0b62e1fe-cf0c-4866-ac9f-c9eebd6f42c9",
                            "internalId": 588637,
                            "type": "PAYMENT_ACCOUNT"
                        }, 
                        {
                            "id": "7a3d9c14-2f0a-4d7b-8c7b-6f28c4a9e9e2",
                            "internalId": 588638,
                            "type": "PAYMENT_ACCOUNT"
                        }, 
                    ]
                }
            ],
            "type": "LEGAL_ENTITY",
            "updatedAt": "2025-08-19T07:53:04.148Z",
            "createdAt": "2025-08-19T07:51:08.110Z"
        },

• Payload example - GET/accounts/{:id} to retrieve the profileId & example with multi-profile

{
    "id": "c785b6bb-cf3b-46b3-bf05-57ab5ce424dc",
    "onboardingId": null,
    "identity": {
        "name": "Walter - Toy",
        "type": "COMPANY",
        "registrationNumber": "50JoRegistrationDOUBLON",
        "registrationCountry": "FR",
        "registrationDate": "1992-03-21"
    },
    "status": "ACCEPTED",
    "profiles": [
        {
            "id": "7463b0a1-ed13-4666-b756-8f291f68d4b4",
            "type": "PROJECT_HOLDER",
            "status": {
                "type": "ACCEPTED",
                "subStatus": null
            },
            "wallets": [
                {
                    "id": "0b62e1fe-cf0c-4866-ac9f-c9eebd6f42c9",
                    "internalId": 588639,
                    "type": "PAYMENT_ACCOUNT"
                }
            ]
        },
        {
            "id": "f1a2c9b8-8c34-4e79-9d3a-85c9186e3f4e4",
            "type": "DONOR",
            "status": {
                "type": "ACCEPTED",
                "subStatus": null
            },
            "wallets": [
                {
                    "id": "b4d67e2a-9c2f-48d3-b412-0f7e6a8c3b77",
                    "internalId": 588640,
                    "type": "TECHNICAL_WALLET"
                }
            ]
        }
    ],
    "information": {
        ....
    }
    "type": "LEGAL_ENTITY",
    "documents": [
      .....
    ],
    "createdAt": "2025-08-19T07:51:08.110Z"
}

Implementation Steps

1. Set Up Webhooks
   Configure webhook endpoints to receive notifications for both account and profile status changes.

2. Handle Notifications
   Implement logic to process different notification types and update your systems accordingly.

3. Monitor Status Continuously
   Regularly check account and profile statuses to ensure onboarding is progressing as expected.