Webhook Catalogue
A full reference of all webhook events emitted by Lorum, organised by category.
To enable events, configure your webhook categories in the portal under Settings > App.
Account
account_opened
Sent when a new account has been opened.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account identifier in the Lorum system |
account_type | enum | Type of account - primary, payment, or virtual |
account_name | string | The name set on the account |
customer_id | uuid | The ID of the customer |
external_id | string | External ID set when the account request was made |
currency | string | ISO currency code for the account |
{
"type": "account_opened",
"event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"event_version": 1,
"account_opened": {
"account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"account_name": "Contractors Inc.",
"customer_id": null,
"external_id": "01H2ZZV055MFPM8FD9RCJWM6R0",
"currency": "AED",
"account_type": "payment"
}
}
account_updated
Sent when an account has been updated.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account identifier in the Lorum system |
account_name | string | The name set on the account |
account_owner | string | The owner name set on the account |
external_id | string | External ID set when the account request was made |
{
"type": "account_updated",
"event_id": "018c35ab-98bf-4390-bd51-858e61a87859",
"event_version": 3,
"account_updated": {
"account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"account_name": "Contractors Ltd.",
"account_owner": "John Contractor",
"external_id": "01H2ZZV055MFPM8FD9RCJWM6R0"
}
}
account_frozen
Sent when an account has been frozen.
This can be sent again for an account that is already frozen, if it is frozen a second time.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account identifier in the Lorum system |
external_id | string | External ID set when the account request was made |
status | enum | Status of the account after the event - frozen |
{
"type": "account_frozen",
"event_id": "019a3c51-7e2b-7d41-9c0e-2f6b8a4d1e37",
"event_version": 1,
"account_frozen": {
"account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"external_id": "01H2ZZV055MFPM8FD9RCJWM6R0",
"status": "frozen"
}
}
account_unfrozen
Sent when an account has been unfrozen and is open again.
This can be sent for an account that is already open, if it is unfrozen without having been frozen.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account identifier in the Lorum system |
external_id | string | External ID set when the account request was made |
status | enum | Status of the account after the event - open |
{
"type": "account_unfrozen",
"event_id": "019a3c58-0a91-7f26-b4d3-6c1e9f02a85b",
"event_version": 1,
"account_unfrozen": {
"account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"external_id": "01H2ZZV055MFPM8FD9RCJWM6R0",
"status": "open"
}
}
account_closed
Sent when an account has been closed.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account identifier in the Lorum system |
external_id | string | External ID set when the account request was made |
status | enum | Status of the account after the event - closed |
{
"type": "account_closed",
"event_id": "019a3c62-d4f8-7b19-8e57-91a3c0b6f2d4",
"event_version": 1,
"account_closed": {
"account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"external_id": "01H2ZZV055MFPM8FD9RCJWM6R0",
"status": "closed"
}
}
Payment
outbound_local_payment_created
A local payment has been initiated.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the payment was made |
transaction_id | uuid | The Lorum transaction identifier |
amount_with_fee | integer | Transaction amount including fee in minor currency (e.g. 100 = 1.00) |
instructed_amount | integer | Transaction amount excluding fee in minor currency |
fee_amount | integer | Fee amount in minor currency |
remitter | RemitterDetails | Details of the payment remitter |
beneficiary | BeneficiaryDetails | Details of the payment beneficiary |
purpose | PurposeCode | Purpose of the transaction |
currency | string | ISO currency code |
external_reference | string | Reference set by the customer when initiating the payment |
external_id | string | External ID set on the create payment request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
fee_source | FeeSourceAccount | Optional fee source account details |
{
"type": "outbound_local_payment_created",
"event_id": "018c35b3-def3-a3bb-792d-f79534562555",
"event_version": 4,
"outbound_local_payment_created": {
"account_id": "018c355c-2413-16df-509f-40e71b142eb3",
"transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
"instructed_amount": 51239,
"amount_with_fee": 51239,
"fee_amount": 0,
"remitter": {
"name": "Monday Inc.",
"identifier": { "iban": "AE220910000000808720471" }
},
"beneficiary": {
"name": "Fulan AlFulani",
"identifier": { "iban": "AE120266712486572167372" }
},
"external_reference": "local*1701708016",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
"timestamp": "2023-12-04T16:40:29.683099191Z",
"purpose": "goods_bought",
"currency": "AED"
}
}
outbound_local_payment_submitted
A local payment has been submitted for processing.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the payment was made |
transaction_id | uuid | The Lorum transaction identifier |
external_id | string | External ID set on the create payment request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "outbound_local_payment_submitted",
"event_id": "018c35b3-e005-fd7b-ea42-aec8c20e521f",
"event_version": 6,
"outbound_local_payment_submitted": {
"account_id": "018c355c-2413-16df-509f-40e71b142eb3",
"transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
"timestamp": "2023-12-04T16:40:29.957851510Z"
}
}
outbound_local_payment_executed
The local payment has been successfully processed.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the payment was made |
transaction_id | uuid | The Lorum transaction identifier |
external_id | string | External ID set on the create payment request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "outbound_local_payment_executed",
"event_id": "018c35b4-030f-a403-dfe2-7c757e94f00b",
"event_version": 7,
"outbound_local_payment_executed": {
"account_id": "018c355c-2413-16df-509f-40e71b142eb3",
"transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
"timestamp": "2023-12-04T16:40:38.927642874Z"
}
}
outbound_local_payment_failed
The local payment attempt was unsuccessful.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the payment was made |
transaction_id | uuid | The Lorum transaction identifier |
external_id | string | External ID set on the create payment request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
failure_reason | FailureReason | Cause of the payment failure |
{
"type": "outbound_local_payment_failed",
"event_id": "018c35b9-fbdc-8081-969a-bc591888d2e6",
"event_version": 12,
"outbound_local_payment_failed": {
"account_id": "018c0027-a9b0-1f65-54ea-fe723844940f",
"transaction_id": "018c35b9-8f58-9b36-370d-b5e3f00705ff",
"failure_reason": { "bank_error": "Manual failure in Portal" },
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
"timestamp": "2023-12-04T16:47:10.300679370Z"
}
}
outbound_local_payment_returned
A previously executed local payment has been returned by the beneficiary's bank.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the payment was made |
transaction_id | uuid | The Lorum transaction identifier for the original payment |
returned_transaction_id | uuid | The Lorum transaction identifier for the return |
amount | integer | Amount in minor currency (e.g. 100 = 1.00) |
remitter | RemitterDetails | Details of the payment remitter |
beneficiary | BeneficiaryDetails | Details of the payment beneficiary |
external_reference | string | Reference set by the customer when initiating the payment |
timestamp | ISO8601 datetime | Timestamp of the return event |
currency | string | ISO currency code |
returned_reason | string | Reason provided by the beneficiary's bank for the return |
{
"type": "outbound_local_payment_returned",
"event_id": "018c35ba-1234-5678-9abc-def012345678",
"event_version": 1,
"outbound_local_payment_returned": {
"account_id": "018c355c-2413-16df-509f-40e71b142eb3",
"transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
"returned_transaction_id": "018c35ba-9876-5432-10fe-dcba98765432",
"amount": 51239,
"remitter": {
"name": "Monday Inc.",
"identifier": { "iban": "AE220910000000808720471" }
},
"beneficiary": {
"name": "Fulan AlFulani",
"identifier": { "iban": "AE120266712486572167372" }
},
"external_reference": "local*1701708016",
"timestamp": "2023-12-05T10:15:30.123456789Z",
"currency": "AED",
"returned_reason": "Account closed"
}
}
inbound_local_payment_settled
An inbound local payment has settled into the account.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account the payment settled into |
transaction_id | uuid | The Lorum transaction identifier |
amount_with_fee | integer | Transaction amount including fee in minor currency |
instructed_amount | integer | Transaction amount excluding fee in minor currency |
fee_amount | integer | Fee amount in minor currency |
remitter | RemitterDetails | Details of the payment remitter |
beneficiary | BeneficiaryDetails | Details of the payment beneficiary |
purpose | PurposeCode | Purpose of the transaction |
currency | string | ISO currency code |
external_reference | string | Reference set by the customer when initiating the payment |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
fee_source | FeeSourceAccount | Optional fee source account details |
{
"type": "inbound_local_payment_settled",
"event_id": "018c35bc-9019-34b2-5210-ff9900d349bd",
"event_version": 40,
"inbound_local_payment_settled": {
"account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
"transaction_id": "018c35bc-9086-638d-0e9a-f1f46ea6146a",
"instructed_amount": 100000000,
"amount_with_fee": 100000000,
"fee_amount": 0,
"remitter": {
"name": "Topup",
"identifier": { "iban": "AE080070000000785666509" }
},
"beneficiary": {
"name": "AED Merchant Account",
"identifier": { "iban": "AE460266386228195554412" }
},
"external_reference": "funding*1701708590",
"timestamp": "2023-12-04T16:49:59.325104057Z",
"purpose": "none",
"currency": "AED"
}
}
fee_debited
A fee has been debited from an account. Triggered when fees are collected separately from the main transaction.
| Field | Type | Description |
|---|---|---|
transaction_id | uuid | Unique identifier of the fee debit transaction |
account_id | uuid | The account from which the fee was debited |
amount | integer | Fee amount in minor currency (e.g. 100 = 1.00) |
timestamp | ISO8601 datetime | Timestamp of when the fee was debited |
fee_target.type | enum | The type of entity the fee was applied to (e.g. transaction) |
fee_target.reference | uuid | Identifier of the entity the fee was charged against |
currency | string | Currency in which the fee was debited |
{
"type": "fee_debited",
"event_id": "49cd3525-bb13-4e85-8df0-a85741c2bc51",
"event_version": 268,
"fee_debited": {
"transaction_id": "019c2978-2271-7bc1-8fd9-c2c183e1f354",
"account_id": "0196b31a-bbd8-7d14-b333-a1465359b52d",
"amount": 918,
"timestamp": "2026-02-04T16:25:31.870483469Z",
"fee_target": {
"type": "Transaction",
"reference": "019c2978-0714-7e93-8f4f-b2c3030e6831"
},
"currency": "AED"
}
}
Transfer
internal_transfer_created
An internal transfer between two accounts has been initiated.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the transfer is made |
transaction_id | uuid | The Lorum transaction identifier |
amount | integer | Amount in minor currency (e.g. 100 = 1.00) |
to_account_id | uuid | The destination account |
reference | string | Reference set by the customer when initiating the transfer |
external_id | string | External ID set on the create transfer request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "internal_transfer_created",
"event_id": "018c35ad-e939-11e1-b8ac-0896580ef2f6",
"event_version": 38,
"internal_transfer_created": {
"account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
"transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
"amount": 1000000,
"to_account_id": "018c355c-2413-16df-509f-40e71b142eb3",
"reference": "transfer-1701707629",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
"timestamp": "2023-12-04T16:33:59.155913761Z"
}
}
inbound_internal_transfer_settled
An internal transfer into the account has completed and settled.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account the transfer settled into |
from_account_id | uuid | The source account |
transaction_id | uuid | The Lorum transaction identifier |
amount | integer | Amount in minor currency (e.g. 100 = 1.00) |
reference | string | Reference set by the customer when initiating the transfer |
external_id | string | External ID set on the create transfer request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "inbound_internal_transfer_settled",
"event_id": "018c35ad-e9ab-ae02-28a0-ebc9d3b70a89",
"event_version": 3,
"inbound_internal_transfer_settled": {
"account_id": "018c355c-2413-16df-509f-40e71b142eb3",
"from_account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
"transaction_id": "018c35ad-e9ab-ae02-28a0-ebc9d3b70a89",
"amount": 1000000,
"timestamp": "2023-12-04T16:33:59.211640Z",
"reference": "transfer-1701707629",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX"
}
}
internal_transfer_settled
A transfer from the account has completed.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the transfer settled |
transaction_id | uuid | The Lorum transaction identifier |
external_id | string | External ID set on the create transfer request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "internal_transfer_settled",
"event_id": "018c35ad-ea8e-031c-55ec-86af02893c79",
"event_version": 39,
"internal_transfer_settled": {
"account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
"transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
"timestamp": "2023-12-04T16:33:59.211640Z"
}
}
internal_transfer_failed
An internal transfer between two accounts was unsuccessful.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The account from which the transfer was attempted |
transaction_id | uuid | The Lorum transaction identifier |
external_id | string | External ID set on the create transfer request |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
failure_reason | FailureReason | Cause of the transfer failure |
{
"type": "internal_transfer_failed",
"event_id": "697cc542-aa22-4ee3-a278-949d59f24b15",
"event_version": 44,
"internal_transfer_failed": {
"account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
"transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
"timestamp": "2023-12-04T16:33:59.211640Z",
"failure_reason": "insufficient_funds",
"external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX"
}
}
Exchange Transfer
outbound_exchange_transfer_created
A currency exchange from one account to another has been initiated.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The source account |
counterpart_account_id | uuid | The destination account |
transaction_id | uuid | The Lorum transaction identifier |
currency | string | Source currency |
amount | integer | Source amount in minor currency (e.g. 100 = 1.00) |
counterpart_currency | string | Destination currency |
counterpart_amount | integer | Destination amount in minor currency |
external_reference | string | Reference set by the customer when initiating the exchange |
rate | decimal | Exchange rate used for the conversion |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "outbound_exchange_transfer_created",
"event_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
"event_version": 29,
"outbound_exchange_transfer_created": {
"account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
"counterpart_account_id": "019342ec-af92-7470-9af9-7543cc6daf71",
"transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
"amount": 10000,
"counterpart_amount": 36615,
"external_reference": "reference-123",
"timestamp": "2024-10-10T07:49:42.487717774Z",
"currency": "USD",
"counterpart_currency": "AED",
"rate": 3.6615
}
}
outbound_exchange_transfer_submitted
A currency exchange has been submitted for processing.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The source account |
transaction_id | uuid | The Lorum transaction identifier |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "outbound_exchange_transfer_submitted",
"event_id": "019482b0-871d-7d54-8346-a066ecc69221",
"event_version": 30,
"outbound_exchange_transfer_submitted": {
"account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
"transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
"timestamp": "2024-10-10T07:49:54.649511283Z"
}
}
outbound_exchange_transfer_executed
The currency exchange has been completed successfully.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The source account |
transaction_id | uuid | The Lorum transaction identifier |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "outbound_exchange_transfer_executed",
"event_id": "019482b0-871d-7d54-8346-a066ecc69221",
"event_version": 31,
"outbound_exchange_transfer_executed": {
"account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
"transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
"timestamp": "2024-10-10T07:49:54.649511283Z"
}
}
inbound_exchange_transfer_settled
The converted funds have settled into the destination account.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The destination account |
counterpart_account_id | uuid | The source account |
transaction_id | uuid | The Lorum transaction identifier |
currency | string | Destination currency |
amount | integer | Destination amount in minor currency |
counterpart_currency | string | Source currency |
counterpart_amount | integer | Source amount in minor currency |
external_reference | string | Reference set by the customer when initiating the exchange |
rate | decimal | Exchange rate used for the conversion |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
{
"type": "inbound_exchange_transfer_settled",
"event_id": "019482b0-8772-7a46-8792-73d9990dabd1",
"event_version": 20,
"inbound_exchange_transfer_settled": {
"account_id": "019342ec-af92-7470-9af9-7543cc6daf71",
"counterpart_account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
"transaction_id": "019482b0-873e-7f40-9ffe-1e3e298cbb10",
"amount": 36615,
"counterpart_amount": 10000,
"external_reference": "reference-123",
"timestamp": "2024-10-10T07:49:54.747094304Z",
"currency": "AED",
"counterpart_currency": "USD",
"rate": 3.6615
}
}
outbound_exchange_transfer_failed
The currency exchange was unsuccessful.
| Field | Type | Description |
|---|---|---|
account_id | uuid | The source account |
transaction_id | uuid | The Lorum transaction identifier |
timestamp | ISO8601 datetime | Timestamp of when the event took place |
failure_reason | FailureReason | Cause of the exchange failure |
{
"type": "outbound_exchange_transfer_failed",
"event_id": "019482c7-c58d-7240-9850-9c76883b54cf",
"event_version": 35,
"outbound_exchange_transfer_failed": {
"account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
"transaction_id": "019482c7-b534-7e55-a2f8-37ddb441866f",
"failure_reason": { "bank_error": "Manual failure in Portal" },
"timestamp": "2024-10-10T08:15:17.983389023Z"
}
}
Onboarding
onboarding_completed
Customer onboarding for a currency has been successfully completed.
| Field | Type | Description |
|---|---|---|
customer_id | uuid | The unique identifier for the customer |
currency | string | ISO currency code for the onboarded currency |
{
"type": "onboarding_completed",
"event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"event_version": 0,
"onboarding_completed": {
"customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"currency": "AED"
}
}
onboarding_failed
Customer onboarding for a currency has failed.
| Field | Type | Description |
|---|---|---|
customer_id | uuid | The unique identifier for the customer |
currency | string | ISO currency code for the onboarded currency |
failure_reason.msg | string | Human-readable description of the failure |
failure_reason.code | ErrorCode | Machine-readable error code |
ErrorCode values:
| Code | Description |
|---|---|
missing_document | A required document is missing |
missing_currency_data | Currency-specific data is missing from the customer record |
no_shareholders | Business customer has no shareholders linked |
insufficient_majority_ownership | Linked shareholders do not meet the 51% ownership threshold |
shareholder_not_onboarded | A shareholder is not onboarded to the specified currency |
business_registration_date_missing | Business registration date is missing |
individual_missing_proof_of_address_document | Individual is missing a proof of address document |
business_missing_proof_of_address_document | Business is missing a proof of address document |
{
"type": "onboarding_failed",
"event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"event_version": 0,
"onboarding_failed": {
"customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"currency": "AED",
"failure_reason": {
"msg": "Individual `018c35aa-4279-83e7-a90f-4b2901246c51` does not have document `passport`",
"code": "missing_document"
}
}
}
Customer
customer_approved
Customer passed the screening and approved.
| Field | Type | Description |
|---|---|---|
customer_id | uuid | The unique identifier for the customer |
{
"type": "customer_approved",
"event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"event_version": 0,
"customer_approved": {
"customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51"
}
}
customer_rejected
Customer failed screening and rejected.
| Field | Type | Description |
|---|---|---|
customer_id | uuid | The unique identifier for the customer |
reason | string | failure reason |
{
"type": "customer_rejected",
"event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"event_version": 0,
"customer_rejected": {
"customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"reason": "compliance reason",
}
}
Updated 8 days ago