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)