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

Results ready

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

Payment Source Created

"type": "payment_source.created"

Payload object type: Payment Source

This webhook is triggered when your customer successfully creates a payment source using the Link SDKs Connect() or CreatePaymentSource() functions.

{
  "payload": {
    "id": "ab172710-740c-452b-a78f-8a36a9cf48ef",
    "customer_id": "0fd6d135-a4be-40ac-9630-1738ced7da69",
    "status": "AWAITING_BENEFICIARY_COOL_OFF",
    "bank_identifier": "LEANMB1",
    "bank_name": "Lean Mock Bank"
  },
  "type": "payment_source.created",
  "message": "A payment source was pre-authorized by your customer.",
  "timestamp": "2021-06-23T14:17:34.342847Z",
  "event_id": "00405221-21fc-4aa2-a237-3edfe4c38411"
}

Beneficiary Created

"type": "payment_source.beneficiary.created"

Payload object type: Payment Source Beneficiary

This webhook is triggered when your customer successfully creates a payment source using the Link SDKs Connect() or CreatePaymentSource() functions. This webhook is also triggered when a destination is added to a payment source using the Link SDK UpdatePaymentSource() function which creates a new beneficiary object within the payment source.

Unlike the payment_source.created webhook, the focal object for this webhook is the beneficiary, which represents the pathway between a payment_source and payment_destination. Many beneficiaries can be created for the same payment source which in the real world allows the payment source to make payments to many destinations.

{
  "payload": {
    "id": "2cd827ab-d0c4-462f-b2a2-12e3ef1b7d8e",
    "customer_id": "0fd6d135-a4be-40ac-9630-1738ced7da69",
    "payment_source_id": "ab172710-740c-452b-a78f-8a36a9cf48ef",
    "payment_destination_id": "99da636d-d022-4e0a-a450-a293ecdcb125",
    "status": "ACTIVE"
  },
  "type": "payment_source.beneficiary.created",
  "message": "A beneficiary was added for a payment source.",
  "timestamp": "2021-06-23T15:59:11.02946Z",
  "event_id": "5cf79ddb-ac0e-43fb-894d-5a54eb6c4856"    
}

Beneficiary Updated

"type": "payment_source.beneficiary.updated"

Payload object type: Payment Source Beneficiary

This webhook is triggered when a beneficiary object changes status from AWAITING_BENEFICIARY_COOL_OFF to ACTIVE. When this webhook is received, the payment source which the beneficiary belongs to can start to make payments to the payment destination that the beneficiary in question refers to.

📘
When received, we suggest notifying the payment_source's customer that payments can now be made through this payment source using a push notification.

{
  "payload": {
    "id": "2cd827ab-d0c4-462f-b2a2-12e3ef1b7d8e",
    "customer_id": "0fd6d135-a4be-40ac-9630-1738ced7da69",
    "payment_source_id": "ab172710-740c-452b-a78f-8a36a9cf48ef",
    "payment_destination_id": "99da636d-d022-4e0a-a450-a293ecdcb125",
    "status": "ACTIVE"
  },
  "type": "payment_source.beneficiary.updated",
  "message": "A beneficiary was updated for a payment source.",
  "timestamp": "2021-06-24T12:27:28.663129Z",
  "event_id": "9a826354-d2ea-499e-9f05-a5ad316ef3f1"
}

Payment Created

"type": "payment.created"

Payload object type: Payment

This webhook is triggered when your customer has successfully initiated a payment or when the payment was unsuccessful while going through the pay() flow within the Link SDK. The status of the payment is reflected in the status field within the payload.

{
  "payload": {
    "id": "66214bdb-5f1a-4127-9ddc-cc44c0446c82",
    "customer_id": "0fd6d135-a4be-40ac-9630-1738ced7da69",
    "intent_id": "b896af3a-1781-4a48-b173-ce4b2ca6a522",
    "status": "ACCEPTED_BY_BANK",
    "amount": 10.17,
    "currency": "AED",
    "bank_transaction_reference": "0H129D0RT04YY"
  },
  "type": "payment.created",
  "message": "A payment object has been created.",
  "timestamp": "2020-06-22T13:15:28.565512Z",
  "event_id": "f4096636-85f3-42f1-8148-3cf9b5377db2"
}

Payment Updated

"type": "payment.updated"

Payload object type: Payment

This webhook is triggered when there is an update to a specific payment. The new status of the payment is reflected in the status field within the payload.

{
  "payload": {
    "id": "e4e672fb-7f3c-43ea-be31-84195a65d0d7",
    "customer_id": "8ad2437d-2815-4b5c-82fd-543d85567668",
    "intent_id": "17e030df-91a9-4463-964c-6656605d5bcf",
    "status": "ACCEPTED_BY_BANK",
    "amount": 670,
    "currency": "AED",
    "bank_transaction_reference": "44778733",
    "end_user_id": "eb3b08f9-4d5e-4ea3-8d28-09b4917a61a9"
  },
  "type": "payment.updated",
  "message": "A payment object has been updated.",
  "timestamp": "2022-10-07T10:43:45.128593273Z",
  "event_id": "db2d5765-a303-4f0a-8bbe-b7a4711cf60b"
}