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

Notification Status	Account Status	Status Trigger	Description
1	`CREATED`	Callback after POST `/account` for a User and a Business relationship	The end-user's account has been successfully created.
2	`ACCEPTED`	N/A	The end-user account has been approved and a wallet has been opened. The onboarding process is now complete.
3	`DENIED`	Regulatory reason	We have declined the activation of the end-user's account, and a wallet will not be opened. The onboarding process is now complete.
4	`BLOCKED`	Entity blocked for regulatory reason or KYC update outdated	End-user is unable to access wallet, the account is blocked.
5	`KYC_UPDATE_REQUESTED`	The next verification date is approaching, and the end-user must review their information.	In most cases, the end-user will simply need to confirm the existing details. However, in some situations, they may be required to submit an additional document or complete the identity verification process (e.g., liveness check). In any case, this does not require any action from you, as Lemonway handles the entire process. The only impact is on the Online Onboarding workflow, where it may affect the generated form.
6	`KYC_UPDATE_REJECTED`		As with the Online Onboarding process, Lemonway may need to request additional information based on the end-user’s responses or if the submitted document(s) are rejected.
7	`KYC_UPDATE_ACCEPTED`	End of Process	The KYC update has been validated by Lemonway’s analysts, allowing the end-user to continue their activity on the partner’s website.

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-users 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.
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

Key	Description
EventDate	Date and time the notification was created. Paris time. Format ISO8601
accountID	ID of the account
profileID	List of profileID linked to this account
ExtId	External ID of the wallet
IntId	Internal ID of the wallet (if any)
Status	Account status
NotifDate	Date when the notification was sent
NotifCategory	Notification ID

👍
Info
An account status is updated upon completion of KYC checks. Depending on whether controls are automatic or manual, results may take from a few minutes up to a maximum of 48 hours.

📘
Note
Webhook notifications can be delayed by up to one hour. We recommend performing a GET request after receiving a webhook to retrieve the latest information.

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"
}

Field	Value	Description
id	c785b6bb-cf3b-46b3-bf05-57ab5ce424dc	Unique identifier of the legal entity.
type	LEGAL_ENTITY	Indicates that this onboarding object represents a company.
status	ACCEPTED	The legal entity has successfully passed all checks.
createdAt	2025-08-19T07:51:08.110Z	Date and time when the legal entity was created in the system.
identity.name	Walter - Toy	Legal name of the company.
identity.type	COMPANY	Specifies that the identity belongs to a company.
identity.registrationNumber	50JoRegistrationDOUBLON	Official company registration number.
identity.registrationCountry	FR	Country where the company is registered.
identity.registrationDate	1992-03-21	Date on which the company was incorporated.
profile.id	7463b0a1-ed13-4666-b756-8f291f68d4b4	Unique ID of the first profile.
profile.type	PROJECT_HOLDER	Role of the profile within the entity.
profile.status	ACCEPTED	Status of this profile.
profile.wallet.id	0b62e1fe-cf0c-4866-ac9f-c9eebd6f42c9	Wallet identifier attached to this profile.
profile.wallet.internalId	588639	Internal numeric identifier for the wallet.

Implementation Steps

Set Up Webhooks Configure webhook endpoints to receive notifications for both account and profile status changes.
Handle Notifications Implement logic to process different notification types and update your systems accordingly.
Monitor Status Continuously Regularly check account and profile statuses to ensure onboarding is progressing as expected.