Set up webhooks

Use webhooks to keep your backend informed when connections, consents, payments and other resources change.

Configure your webhook endpoint before testing customer journeys. A customer returning from their bank does not, by itself, confirm the final outcome.

Before you start

You need:

  • Access to your application's webhook configuration in the Lean Dashboard.
  • An HTTPS endpoint that accepts POST requests.
  • Your application's webhook secret.

Find your webhook secret under Development → Integration settings. Owner and Admin roles can view it by default. Developer roles need the additional permission to view it.

The webhook secret is separate from your OAuth client secret.

1. Configure your endpoint

In the Lean Dashboard, select your application and environment, then open Development → Webhooks.

Configure your endpoint URL and subscribe to the events required by your integration.

For example, your application might receive notifications at:

https://api.example.com/webhooks/lean

Use separate configuration for Sandbox and Production so test events cannot update live customer records.

Choose your subscriptions

Choose events based on the journeys your application supports.

Product areaUpdates your integration needs to handle
Data & InsightsBank connections, consent changes and completion of the information retrieval needed for insights.
PaymentsPayment creation, payment updates and Account on File consent changes.
ReconciliationChanges to the reconciliation outcome of a payment.
PayoutsBeneficiary readiness and payout progress.
RefundsRefund transaction updates.

Follow the relevant product guide for the exact event types, payloads and actions to take.

2. Verify incoming requests

Validate each webhook before accepting it for processing.

Lean signs the request body using HMAC-SHA512 and your webhook secret. The signature arrives in the lean-signature header with a sha512= prefix.

Your handler should:

  1. Preserve the raw request body.
  2. Calculate its HMAC-SHA512 using your webhook secret.
  3. Compare the result with the supplied signature using a constant-time comparison.
  4. Reject requests with missing or invalid signatures.

Verify the signature against the original body bytes. Parsing JSON and serialising it again can change the body and cause verification to fail.

Restrict incoming traffic

You can also allowlist Lean's webhook source IPs.

EnvironmentSource IP
UAE Production193.123.78.188
UAE Production — disaster recovery89.168.106.22
UAE Production — disaster recovery129.151.134.206
UAE Sandbox193.123.89.181

DNS lookup names are webhooks.leantech.me for Production and webhooks.sandbox.leantech.me for Sandbox.

If your firewall uses resolved addresses, keep its rules updated. Continue verifying signatures when using an IP allowlist.

3. Read the event

Lean webhooks share an outer structure. The fields inside payload depend on the event type.

FieldTypeDescription
typeStringIdentifies the event, such as payment.updated. Use it to route the event to the appropriate handler.
payloadObjectContains the resource information associated with the event.
messageStringDescribes the event. Use structured fields rather than this text for application logic.
timestampStringRecords when the event occurred.
event_idStringUniquely identifies the event as a UUID. Use it to detect repeated deliveries.

The following example illustrates the shared structure only. Its empty payload is a placeholder for the event-specific fields.

{
  "type": "payment.updated",
  "payload": {},
  "message": "A payment object has been updated.",
  "timestamp": "2026-10-30T10:00:00.000000Z",
  "event_id": "cce42859-055b-4271-b4c0-b94d54a3b894"
}

Use the identifiers inside the product's payload to associate the update with your stored resource. The event_id identifies the event, not the payment, consent or connection.

4. Acknowledge and process the event

Return HTTP 200 within 10 seconds. Another status code or a timeout triggers retries at 1, 2, 5, 10, 60 and 180 minutes after the initial delivery.

We recommend separating receipt from business processing:

  1. Verify the signature and validate the event.
  2. Store the event durably or enqueue it for processing.
  3. Return HTTP 200.
  4. Process the event in a background worker.

Only acknowledge receipt once the event is safely stored. If storage fails, return an error so Lean can retry.

After you acknowledge an event, your application is responsible for retrying any failed background processing.

Handle repeated deliveries

Use event_id to prevent the same event from being processed twice. Make the duplicate check and storage operation atomic so concurrent deliveries cannot both trigger processing.

For an event you have already accepted, return HTTP 200 without repeating its business action.

Also protect business actions themselves against duplication. For example, receiving another notification about a payment must not credit the customer's balance a second time.

Handle delayed updates

Design your handler so a delayed event cannot overwrite a newer resource state.

If an update conflicts with your stored state, retrieve the resource through the relevant API where available and apply the product's lifecycle rules.

Use each product guide to distinguish progress from completion. Receipt of a webhook, or a bank's acceptance of an operation, does not necessarily mean funds have arrived.

5. Recover missed events

You can resend webhooks from the Lean Dashboard to retry delivery to your endpoint—for example, after resolving an issue with your webhook handler.

Your handler should apply the same signature verification and duplicate-handling rules to resent webhooks.

For recovery across a time window, use the Events API to identify and process missing events.

GET /events/v1 lists events created by Lean and sent over webhooks during the past 90 days. It supports pagination and filters for creation time and event type.

To recover:

  1. Identify the time window affected.
  2. Retrieve all pages of events for that window.
  3. Compare their event_id values with your stored events.
  4. Process missing events through the same duplicate-safe business handlers.
  5. Check the current resource state where needed before applying an older update.

The Events API retrieves event records; it does not itself resend them to your endpoint.

Events API reference →

6. Test your handler

Complete a Sandbox journey that produces an event your application subscribes to, then confirm that:

  • The signature validates using the correct webhook secret.
  • The event is stored before your endpoint returns HTTP 200.
  • Repeated delivery does not repeat the business action.
  • A failed background job can be retried by your application.
  • Delayed events do not overwrite newer state.
  • Missing or invalid signatures are rejected.
  • Missed events can be recovered through the Events API.

Monitor receipt failures and processing failures separately so you can identify whether an issue occurred before or after acknowledgement.

Next steps

Continue with the product guide for the flow you are building. It will explain the required subscriptions, event payloads and how each update affects your integration.


Did this page help you?