Webhook Library

Entity created

"type": "entity.created"

This webhook is triggered when your customer successfully connects their account through the Link SDK's connect(). The entity object is used by you to retrieve data from your customer's bank account. Where the entity_id serves as a token representing the holding bank account.

{
	"type": "entity.created",
	"message": "An entity object has been created.",
	"payload": {
  	"id": "dd64bba9-9446-4ca0-b9ed-bec2b2a49024",
		"app_user_id": "lean_test_framework_user_1678954843328",
		"customer_id": "a8e9bf82-245a-4f5c-b048-9024fd7910cb",
		"permissions": [
    	"transactions", "identity", "identities", "accounts",
    	"standing_orders", "direct_debits", "scheduled_payments", "beneficiaries"
    ],
    "bank_details": {
    	"logo": "https://cdn.leantech.me/img/banks/white-lean.png",
      "name": "Lean SAMA Open Banking MockBank",
      "account_type": "BUSINESS" | "PERSONAL",
      "identifier": "LEA1_SAMAOB_SAU",
      "main_color": "#1beb75",
      "background_color": "#ffffff"
    }
  }
}

Entity updated

"type": "entity.updated"

This webhook is triggered when there is a change in the consents for the entity. This happens when either your customer successfully connects again their account through the LinkSDK's connect() or the customer revokes the consent. For the first time, you will receive an entity.created webhook.

{
 	"type": "entity.updated",
  "message": "An entity object has been updated.",
  "payload": {
    "id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "app_user_id": "lean_test_framework_user_1678955197525",
    "customer_id": "22df5cab-1002-4835-bc78-5d1854b3fc69",
    "permissions": [
      "transactions", "identity", "identities", "accounts",
      "standing_orders", "direct_debits", "scheduled_payments", "beneficiaries"
    ],
		"bank_details": {
      "logo": "https://cdn.leantech.me/img/banks/white-lean.png",
      "name": "Lean SAMA Open Banking MockBank",
      "identifier": "LEA1_SAMAOB_SAU",
      "account_type": "BUSINESS" | "PERSONAL",
      "main_color": "#1beb75",
      "background_color": "#ffffff"
    } 
  }
}

Entity Data Refresh Updated

"type": "entity.data.refresh.updated"

The entity.data.refresh.updated webhook notify the notify progress of population of data for the connected entity where a final entity.data.refresh.updated webhook with status FINISHED once all requests have been completed and data is available in Lean store.

More details about data workflow here.

{
  "type": "entity.data.refresh.updated",
  "message": "An entity data refresh state has been updated.",
  "payload": {
    "refresh_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "entity_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "customer_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "status": "PENDING/FINISHED",
    "data_status": {
      "accounts": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
      "identity": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
      "account_data": [
	      {
		      "account_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
		      "balance": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "identity": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transactions": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "scheduled_payments": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "direct_debits": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "standing_orders": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "beneficiaries": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transaction_availability": {
			      "start": "<DateTime>",
			      "end": "<DateTime>"
			    }
		    },{
		      "account_id": "b5098d49-840d-459e-9ea1-d02901af9b8c",
		      "balance": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "identity": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transactions": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "scheduled_payments": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "direct_debits": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "standing_orders": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "beneficiaries": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transaction_availability": {
			      "start": "<DateTime>",
			      "end": "<DateTime>"
			    }
		    }
      ]
    }
  }
}

Results ready (deprecated)

"type": "results.ready"

The results ready webhook is triggered after Lean's system has retrieved data requested to be delivered asynchronously.

{
  "payload": {
    "id": "dbd310a2-ebd9-4a0f-ae10-0f82f25f1bff"
  },
  "type": "results.ready",
  "message": "Your results are ready.",
  "timestamp": "2021-09-02T15:38:54.573741Z",
  "event_id": "f8752072-cef2-4056-9ff0-d5d2aa1e4558",
}

Bank availability updated

"type": "bank.availability.updated"

The Bank Availability webhook is triggered when a bank is taken offline or online by either Lean or by you in the Application Dashboard. This webhook is sent only when a bank is taken offline or online for bank data (Open Banking). When a bank is unavailable usage of the LinkSDK is restricted for end-users.

{
  "payload": {
    "identifier": "BANK1_KSA",
    "availability": {
      "active": {"payments": true, "data": true},
      "enabled": {"payments": true, "data": true}
    }
  },
  "type": "bank.availability.updated",
  "message": "The bank status has been updated.",
  "timestamp": "2021-12-14T15:06:46.083515Z",
  "event_id": "103586d6-e88c-40ba-aa0e-c6ee255aaf2e"
}

IBAN account verification bank availability updated

"type": "iban_account_verification.bank.availability.updated"

The IBAN Account Verification Bank Availability webhook is triggered when a bank is taken offline or online by either Lean or by you in the Application Dashboard. This webhook is sent only when a bank is taken offline or online for IBAN Account Verification. When a bank is unavailable usage you will get an error when attempting to make a call to the IBAN Account Verification API.

{
  "payload": {
	  "country_code": "SA",
	  "bank_code": "80",
	  "availability": {
			"global": "enabled", // globally enable/disable the bank
			"account_type": {
				"personal": {
					"match": "enabled",
					"no_match": "enabled"
				},
				"freelancer": {
					"match": "enabled",
					"no_match": "enabled"
				},
				"business": {
					"match": "enabled",
					"no_match": "enabled"
				}
			}
		}
  },
  "type": "iban_account_verification.bank.availability.updated",
  "message": "IBAN account verification bank availability has been updated",
  "timestamp": "2021-12-14T15:06:46.083515Z",
  "event_id": "103586d6-e88c-40ba-aa0e-c6ee255aaf2e"
}

Report generated

"type": "report.generated"

The Report Generated webhook is triggered when a new report is successfully generated if you are using HyperLink and Reports via API functionality.

{
	"type": "report.generated",
  "message": "A report was generated.",
  "timestamp": "2021-12-14T15:06:46.083515Z",
  "event_id": "103586d6-e88c-40ba-aa0e-c6ee255aaf2e",
  "payload": {
     "customer_id": "dbd310a2-ebd9-4a0f-ae10-0f82f25f1bff",
     "report_id": "f8752072-cef2-4056-9ff0-d5d2aa1e4558"
  }
}

Report failed

"type": "report.failed"

The Report Failed webhook is triggered when something goes wrong during data retrieval or report generation if you are using HyperLink and Reports via API functionality.

{
	"type": "report.failed",
  "message": "A report couldn't be generated.",
  "timestamp": "2021-12-14T15:06:46.083515Z",
  "event_id": "103586d6-e88c-40ba-aa0e-c6ee255aaf2e",
  "payload": {
     "customer_id": "dbd310a2-ebd9-4a0f-ae10-0f82f25f1bff",
  }
}

HyperLink unsupported bank request created

"type": "hyperlink.unsupported_bank_request.created"

The HyperLink unsupported bank request created webhook is triggered when a customer requests to connect a bank account for a bank that Lean does not support at the moment. You can use this event to trigger a fallback flow so that your customer can complete the journey via another method (e.g.: uploading a bank statement).

{
  "type": "hyperlink.unsupported_bank_request.created",
  "message": "The customer requested unsupported bank.",
  "timestamp": "2021-12-14T15:06:46.083515Z",
  "event_id": "103586d6-e88c-40ba-aa0e-c6ee255aaf2e",
  "payload": {
     "customer_id": "dbd310a2-ebd9-4a0f-ae10-0f82f25f1bff",
     "bank_identifier":"STC_SAU"
  }
}