Whenever an account gets synchronized with the associated financial provider and new data is fetched, your application can asynchronously be notified via webhooks about certain events. For which events your application gets called depends on the notification key used, whose format is described in the following section.
For a notification to be considered as delivered successfully, the webhook endpoint should return HTTP response codes in the range of 2xx or 3xx. Everything else will be assumed an error.
Callback Request Headers
When a notification is triggered, the configured callback endpoint is called by the finX API setting the User-Agent header to finx-notification/<finx-api-version>. E.g.
User-Agent: finx-notification/1.0.0
Observe Keys
When configuring a new notification, you have to specify an observe key which defines the trigger condition for the notification. The observe key is composed of a path and a number of query parameters, similar to a URL without scheme and host part.
A client is only allowed to configure a notification of a certain type if he has the required scope for this specific notification.
Account balance
Triggered when the respective account balance changes
| Item | Value |
|---|---|
| Key | /rest/accounts/{account-id}/balance?inferior_limit=<int> |
| Scope | balance=ro |
Parameters
| Name | In | Description |
|---|---|---|
account-id | path | finX account ID |
inferior_limit | query | Trigger if the balance of the account is below this value |
Transactions of Account
Triggered when an account has received new transactions
| Item | Value |
|---|---|
| Key | /rest/accounts/{account-id}/transactions?<params> |
| Scope | transactions=ro |
Parameters
All query-parameters for this observe key can be combined with include_pending but not amongst each other.
| Name | In | Description |
|---|---|---|
account-id | path | finX account ID. |
include_pending | query | Also consider pending transactions. |
more_expenses_then_deposits | query | Trigger if the sum of expenses in the current month exceeds the sum of deposits. |
current_month_expense_goal | query | Trigger if the sum of expenses in the current month exceeds the provided value. |
single_expense_goal | query | Trigger for expense transactions exceeding the provided value. |
single_deposit_goal | query | Trigger for expense transactions exceeding the provided value. |
purpose | query | Trigger on transactions whose purpose contains the provided value. |
name | query | Trigger on transactions whose sender/receiver name contains the provided value. |
All transactions
| Item | Value |
|---|---|
| Key | /rest/transactions |
| Scope | transactions=ro |
Parameters
All query-parameters for this observe key can be combined with include_pending but not amongst each other.
| Name | In | Description |
|---|---|---|
include_pending | query | Also consider pending transactions. |
more_expenses_then_deposits | query | Trigger if the sum of expenses in the current month exceeds the sum of deposits. |
current_month_expense_goal | query | Trigger if the sum of expenses in the current month exceeds the provided value. |
single_expense_goal | query | Trigger for expense transactions exceeding the provided value. |
single_deposit_goal | query | Trigger for expense transactions exceeding the provided value. |
purpose | query | Trigger on transactions whose purpose contains the provided value. |
name | query | Trigger on transactions whose sender/receiver name contains the provided value. |
Auto-sync error
Triggered when the saved PIN of a user is not accepted from the corresponding bank while performing an auto sync.
| Item | Value |
|---|---|
| Key | /rest/accounts/{account-id}/sync?wrong_pin=1 |
| Scope | balance=ro transactions=ro |
Parameters
| Name | In | Description |
|---|---|---|
account-id | path | finX account ID |
wrong_pin | query | Trigger if the PIN of the provider access was reported to be in this state. |
Consent rejected
Triggered when the consent the user granted earlier is rejected by the bank (for example when the consent is expired or the user has already rejected the consent on bank side).
| Item | Value |
|---|---|
| Key | /rest/accesses?consent_rejected=1 |
| Scope | balance=ro transactions=ro |
Test-notification
Triggered immediately. This special notification key can be used to test the delivery of
notifications. The notification message will be sent immediately and no registration occurs.
| Item | Value |
|---|---|
| Key | /rest/notifications/test |
| Scope |
Notification payload
The notification payload you receive on the webhook endpoint is a JSON object with the following fields:
| Key | Description |
|---|---|
notification_id | The ID of the notification in finx, you also get the ID of the notification when creating it |
notification_uri | The URI you provided when creating the notification, this is the URI of the endpoint which will receive the webhook call on your end |
observe_key | The observe_key used to create the notification |
state | This is the value you provided when creating the notification, it could be used to identify the webhook on your end |
href | Where supported, this is the path you can HTTP GET from finx that will return you the objects that triggered the notification (currently only "Consent rejected" notifications support this, you get an href to a credential object which was rejected by the Bank) |