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" |
| Investments | Delivers investment account data (securities, positions, transactions) when processing completes | Wealth data payload |
| 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:
- Your webhook URL.
- The instance (environment) where the webhook should be configured.
- 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 |
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.
