Skip to main content

Webhooks

Overview​

Webhooks are HTTP callbacks which can be used to send notifications to your service/server when data in a user on your client has been changed. Rather than making an API call, finoOS2 sends an HTTP request with the data that has been changed to an endpoint you configure.

Setup​

The webhooks module allows you to set up such user-defined HTTP callbacks by subscribing to events.

Using the webhook module requires the following:

  • Make sure your client has the webhooks scope to have access to the webhooks module
  • Create a webhook endpoint on your server
  • Use the finoOS2 webhook module to set up your webhook
    • Select your preferred HTTP method that shall be used to send the event related data to your webhook
    • Pick one or multiple events you want to subscribe to from the event list below
    • (Optional) generate a secret to secure your webhook
    • Create your webhook
  • Make sure your webhook endpoint can process the payload sent by finoOS2.
  • Send a 2XX http status code back after processing the payload to signal finoOS2 everything went fine
  • If the webhook response returns an HTTP status code above 299, a retry mechanism is triggered. After a certain number of failed attempts, the process stops.

Securing The Webhook​

Before you create a webhook with our webhooks module. Consider to securing the webhook you want to configure by generating a secret and configure you webhook with it. finoOS2 does nothing with your secret but sending the secret along with the payload that gets send after a subscribed event triggers on a user. Your webhook endpoint needs validate the secret to accept the request on your server.

If you already have configured a webhook and want to secure it afterwards. You can update your webhook with a secret.

The Payload​

After setting up and optionally securing your webhook. It is time to receive the payload associated to the subscribed events after an event triggers. Down below you can see the generic payload that gets sent to your configured endpoint.

  • webhookID represents the unique identifier of the webhook
  • userID represents the user experiencing the change in data
  • customUserID is a identifier you can choose on create user
  • tenantID under which tenantID the user was created
  • correlationID which calculation process this event belongs to
  • correlationTimestamp when the calculation process was started
  • secret to secure your webhook
  • event that got triggered
  • data that changes relevant to the event that got triggered.
The generic payload

Type: object

Properties

  • webhookID
    • Type: string
  • userID
    • Type: string
  • customUserID
    • Type: string
  • tenantID
    • Type: string
  • correlationID
    • Type: string
  • correlationTimestamp
    • Type: string
  • secret
    • Type: string
  • event
    • Type: string
  • data
    • Type: object

Headers​

Along with the payload additional headers are sent to your configured webhook. These headers are:

  • X-Request-Id representing a unique identifier for the request or event trigger. For example used to trace back the path the event took.
  • FinoOS-Tenant-ID representing the tenant the event belongs to.

Subscribable Events And Their Payloads​

Banking
transactions.raw

Type: object

Properties webhook data payload contains Accounts with empty tags field.

transactions.raw.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
transactions

Type: object

Properties webhook data payload contains Accounts.

transactions.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
ubasyncerror

This event is triggered if our automatic banking sync cannot be successfully completed. The user consent is expired and a user action is required to renew the sync with /management or /sync (session). Otherwise there is a temporary issue with our infrastructure.

Type: object

Properties

  • errorEvent
  • Type: string
  • errorData
  • Type: object
  • Properties
  • msg
  • Type: string
  • bankLoginID
  • Type: string
  • type
  • Type: string
  • The value is restricted to the following:
  1. "CHALLENGE_REQUIRED"
  2. "ERROR"
  • timestamp
  • Type: string
Categorization
categorization

Type: object

Properties webhook data payload contains Categorization.

categorization.diff

Type: object

Properties webhook data payload contains Categorization only containing transactions with changed tagging.

General Analytics
account-detection

Type: object

Properties webhook data payload contains Account-Detection.

account-detection.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
contracts

Type: object

Properties webhook data payload contains Contracts.

Person Analytics
person-income

Type: object

Properties webhook data payload contains Person-Income.

person-income.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
person-spending

Type: object

Properties webhook data payload contains Person-Spending.

person-spending.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
person-risk

Type: object

Properties webhook data payload contains Person-Risk.

person-risk.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
person-household-budget

Type: object

Properties webhook data payload contains Person-Household-Budget.

person-household-budget.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
person-adult-check

Type: object

Properties webhook data payload contains Person-Adult-Check.

person-adult-check.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
person-living-situation

Type: object

Properties
webhook data payload contains Person-Living-Situation.

person-living-situation.notification

webhook data payload contains notification message without raw data.
Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
    • Type: string
  • service
    • Type: string
    • The finoos2 service which triggered the notification
credit-rating.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
renter-information

Type: object

Properties webhook data payload contains Renter-Information.

renter-information.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
Company Analytics
company-cash

Type: object

Properties webhook data payload contains Company-Cash.

company-cash.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-liquidity

Type: object

Properties webhook data payload contains Company-Liquidity.

company-liquidity.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-foreign-payment

Type: object

Properties webhook data payload contains Company-Foreign-Payments.

company-foreign-payment.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-risk

Type: object

Properties webhook data payload contains Company-Risk.

company-risk.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-credit

Type: object

Properties webhook data payload contains Company-Credits.

company-credit.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-insurance

Type: object

Properties webhook data payload contains Company-Insurances.

company-insurance.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-investment

Type: object

Properties webhook data payload contains Company-Investments.

company-investment.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-internal-booking

Type: object

Properties webhook data payload contains Company-Internal-Bookings.

company-internal-booking.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-staff

Type: object

Properties webhook data payload contains Company-Staff.

company-staff.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-customer-supplier

Type: object

Properties webhook data payload contains Company-Customer-Supplier.

company-customer-supplier.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
company-top-category

Type: object

Properties webhook data payload contains Company-Top-Categories.

company-top-category.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
Cockpit
companycockpit

Type: object

Properties webhook data payload contains CompanyCockpit with the type company.

personcockpit

Type: object

Properties webhook data payload contains PersonCockpit with the type person.

cockpit.approved

This event is triggered when a customer approves a cockpit and so also unlocks it for advisor access.

Type: object

Properties

  • cockpitID
  • Type: string
  • advisorID
  • Type: string
cockpit.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
cockpitrecommendations.notification

webhook data payload contains notification message without raw data. Signals availability of new raw data to fetch from corresponding finoos2 service.

Type: object

Properties

  • message
  • Type: string
  • service
  • Type: string
  • The finoos2 service which triggered the notification
personcockpit-recommendations

Type: object

Properties webhook data payload contains Recommendations.

companycockpit-recommendations

Type: object

Properties webhook data payload contains Recommendations.