Introduction

Webhooks allow your application to react to events happening in LYNKS in real time. Instead of polling the API to check for changes, LYNKS sends an HTTP POST request to your configured endpoint whenever a subscribed event occurs — such as a payment being processed by the bank or a new bank statement becoming available.

Any system that can receive HTTP requests can subscribe to LYNKS webhook events, making this integration approach suitable for ERP systems, custom applications, and automation platforms.

📘

Webhook setup

Webhook configuration requires setup by Finologee's support team. Contact [email protected] to assess your infrastructure requirements and configure webhook subscriptions for your tenant.

Prerequisites

Webhooks are available to API users and require your endpoint to be reachable over HTTPS. Before requesting setup, ensure your system can:

• Accept inbound HTTPS POST requests from LYNKS servers
• Parse a JSON request body
• Validate HMAC-SHA256 request signatures

No specific LYNKS user permission is required to receive webhooks, but the integration must be configured by Finologee's support team for your tenant.

How webhooks work

When a subscribed event occurs in LYNKS, the platform sends an HTTP POST request to your configured endpoint. Your application receives the event payload, processes it, and responds with an HTTP 2xx status code to acknowledge receipt.

If your endpoint does not return a 2xx response, LYNKS retries the delivery using exponential backoff.

Supported events

You can subscribe to the following events:

Webhook payload

Each webhook delivery is an HTTP POST request with a JSON body containing the event details.

Payload structure

{
  "eventId": "01946f4c-88e8-7dd4-8179-6bfc3b873e4e",
  "eventObject": "TRANSACTION",
  "event": "TRANSACTION_PROCESSED_BY_BANK",
  "timestamp": "2025-01-16T14:30:00Z",
  "data": {
    "creditTransferId": "123"
  },
  "links": {
    "self": "https://tenant.lynks.lu/v2/credit-transfers/123"
  }
}

Signature verification

Each webhook request includes an X-Signature-SHA256 header containing an HMAC-SHA256 signature. You should verify this signature to confirm the request originates from LYNKS and has not been tampered with.

To verify the signature:

1. Extract the value from the X-Signature-SHA256 header.
2. Compute an HMAC-SHA256 of the raw request body using your shared secret.
3. Compare your computed signature with the header value.

⚠️

Always verify signatures

Process only webhook requests with a valid signature. Requests with missing or invalid signatures should be rejected to protect your integration from spoofed events.

Technical specifications

Delivery specifications

Endpoint requirements

Your webhook endpoint must:

• Be accessible over public HTTPS
• Return an HTTP 2xx response within a reasonable timeout
• Handle duplicate deliveries idempotently (in case of retries)

Best practices

Follow these recommendations for a reliable webhook integration:

• Respond immediately — Return HTTP 2xx as soon as you receive the request, before performing any processing. Use asynchronous processing for any business logic to avoid timeout failures.
• Handle retries idempotently — Use the eventId field in the payload to detect and deduplicate retries, so the same event is not processed more than once.
• Always verify signatures — Validate the X-Signature-SHA256 header on every incoming request before processing the payload.
• Use the links.self URL — Fetch the full resource details from the API using the provided link rather than relying solely on the webhook payload data.
• Log all incoming events — Keep a log of received webhook payloads for debugging and audit purposes.
• Test before going live — Validate your endpoint with a sandbox tenant before enabling webhooks in production.

Related documentation

Explore related sections to deepen your understanding:

Core Concepts

• Permissions - Roles and access control

Platform Features

• Outgoing payments - Credit transfers and payment statuses
• Direct debit - Collections and mandate management
• Reports - Bank statements and account statement events

Core Concepts

• Notifications - In-app, email, SMS, and webhook alerts

Support

For assistance with webhook setup, endpoint configuration, or troubleshooting delivery failures, contact the Finologee support team at [email protected].