Webhooks

Set up webhooks to receive customer data automatically from Flinks without polling the API.

Webhooks allow you to receive customer data automatically when processing completes, eliminating the need to poll the API for results.

Instead of calling /GetAccountsDetail or /GetAccountsDetailAsync repeatedly, Flinks sends a POST callback to your endpoint with the JSON result as soon as data extraction is complete.

Webhook types

Flinks supports the following types of webhooks:

Type	Description	Payload
KYC	Delivers personal information (name, address, email, phone) as soon as it’s fetched from the FI — before full account data is ready	KYC holder data with "ResponseType": "KYC"
GetAccountsDetail	Delivers the full account data payload (KYC + IBV + transactions) when processing completes	Same as a /GetAccountsDetail 200 response with "ResponseType": "GetAccountsDetail"
Flinks Pay Events	Delivers payment status updates for Flinks Pay transactions (e.g., payment initiated, completed, failed)	Payment event data
Flinks Upload Fraud Alerts	Delivers fraud alert notifications when suspicious documents are detected through Flinks Upload	Fraud alert data

The KYC webhook is delivered as soon as the customer’s personal information is processed, without waiting for full account data. This is useful for time-sensitive identity verification. You will still receive a separate GetAccountsDetail webhook once all data is processed.

Enabling webhooks

To enable webhooks on your instance, open a ticket via the Flinks Support Portal with the following information:

1. Your webhook URL.
2. The instance (environment) where the webhook should be configured.
3. Flinks configures your instance to send callbacks to your URL.

Endpoint requirements

Your webhook endpoint must:

• Accept HTTP POST requests
• Respond with an HTTP 200 status code to confirm receipt
• Have a valid SSL certificate (self-signed certificates are not accepted)

Delivery failure handling

Behavior	Detail
Retry attempts	Up to 10 retries per failed delivery
Retry interval	30 minutes between attempts
Failure definition	Any response other than HTTP 200 is treated as a failure

Custom tags in webhooks

If you pass a Tag parameter in the Flinks Connect iframe URL, the tag value is included in the webhook payload. This allows you to correlate webhook data with your internal records.

{
  "Tag": "clientUserId=abc123",
  "ResponseType": "GetAccountsDetail",
  "HttpStatusCode": 200,
  "Accounts": [...],
  "Login": {...},
  "Institution": "...",
  "RequestId": "..."
}

Reconciling user accounts

You can embed your internal UserId as a custom tag during the Flinks connection flow. When the webhook payload is delivered, it includes both this tag and the Flinks LoginId — making it straightforward to map your internal user records to their corresponding Flinks connection without any additional lookups.

Limitations

Limitation	Detail
No Attributes payloads	Webhooks deliver raw aggregated data (e.g., GetAccountsDetail), not Attributes analysis. Use the webhook payload as a trigger for your server to call an Attributes endpoint (e.g., /GetIncomeAttributes or /GetLendingAttributes) to enrich the data.
No sandbox testing	Webhooks cannot be tested in sandbox environments. Use a staging or production instance.
Single URL per environment	Each instance can only have one webhook URL configured. All webhook types are delivered to the same URL.

Fraud alert webhooks

If you have Flinks Upload enabled, you can also configure webhooks to immediately receive fraud alert notifications when suspicious documents are detected. These alerts can return a manual review or deny verdict based on the fraud signals found. For more on fraud signals, see Document Processing. Contact your Flinks Representative or open a ticket via the Support Portal to enable fraud alert webhooks.

Related resources

• HMAC Signature Validation
• Webhooks API Reference
• Retrieve Account Data