Webhooks
Receive real-time event notifications for payments, transfers, account changes, and customer onboarding. Covers setup, webhook structure, retries, and IP allowlisting.
Webhooks allow you to receive real-time notifications when events occur in your Lorum integration. Rather than polling the API for updates, Lorum pushes event data to a URL you configure - covering payments, transfers, currency exchanges, account changes, and customer onboarding.
All webhooks are disabled by default and must be enabled per category.
Configuring Webhooks
Webhooks are configured in the Lorum portal under Settings > App.
Two things need to be set up:
Webhook URL
A single URL that receives all webhook events for your organisation. This is set once and applies across all enabled categories.
Webhook Categories
Each category must be enabled individually. Only enabled categories will send events to your webhook URL. See Webhook Catalogue for the full list of events per category.
| Category | Description | Events |
|---|---|---|
| Account | Account lifecycle and updates | account_opened, account_updated |
| Payment | Local payment operations (inbound and outbound) | outbound_local_payment_created, outbound_local_payment_submitted, outbound_local_payment_executed, outbound_local_payment_failed, outbound_local_payment_returned, inbound_local_payment_settled, fee_debited |
| Transfer | Internal transfers between accounts | internal_transfer_created, inbound_internal_transfer_settled, internal_transfer_settled, internal_transfer_failed |
| Exchange Transfer | Currency exchange operations between accounts | outbound_exchange_transfer_created, outbound_exchange_transfer_submitted, outbound_exchange_transfer_executed, inbound_exchange_transfer_settled, outbound_exchange_transfer_failed |
| Onboarding | Customer onboarding status updates | onboarding_completed, onboarding_failed |
Webhook Structure
Headers
Lorum sends the following headers with every webhook request:
| Header | Type | Description |
|---|---|---|
X-Fuse-Timestamp | ISO-8601 timestamp | The time the webhook was sent, e.g. 2023-06-19T12:44:47Z |
Body
Webhook bodies are JSON-encoded. All events share the same top-level structure:
| Field | Type | Description |
|---|---|---|
type | string | The event type, e.g. outbound_local_payment_executed |
event_id | uuid | Unique identifier for this event |
event_version | integer | The webhook schema version |
payload | object | Event-specific data, nested under the event type name |
Example:
{
"type": "account_opened",
"event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
"event_version": 1,
"account_opened": {
"account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
...
}
}
Webhook Retries
If Lorum receives a non-success response from your endpoint, the webhook will be retried for up to 12 hours using an exponential backoff policy.
To prevent duplicate processing, ensure your webhook handler is idempotent - use the event_id field to deduplicate events your system may receive more than once.
IP Allowlist
Lorum webhooks are sent from the following IP addresses. Add these to your allowlist if your infrastructure restricts inbound traffic by IP.
| Sandbox | Production |
|---|---|
| 16.18.31.133 | 16.62.35.28 |
| 51.34.107.239 | 16.63.177.47 |
| 51.96.70.57 | 16.63.180.53 |
Updated 4 days ago