Webhooks

The upSWOT system has a facility to automatically send HTTP requests (webhooks) to subscribed listener URLs at the different stages (events) during the SMB Users’ data connection, sharing, and update process.

Webhook Triggers (Event Types)

The following events can trigger webhooks:

RawData: the raw unstructured data has been successfully fetched from the SMB User’s connected app.
NormalizedData: the data from the SMB User’s connected app has been successfully normalized and structured.
ReadyToUseData: data processing has been successfully completed, and ready-to-use data (KPIs, Insights, benchmarks) has been calculated.
Error: An error occurred during one of the stages of the SMB Users’ data-sharing process.
Suspended: The SMB User has suspended data updates for the app.
Disconnected: The SMB User has disconnected the app and deleted all of its previously shared data.

Webhook Subscriptions

To start receiving webhook requests, you will need to subscribe to one or several events by using the Create subscription API endpoints. The webhook requests will be sent to the callback URL specified in the subscription, which you will need to configure on your side.
The following events are available for subscription:

RawData
NormalizedData
ReadyToUseData

After subscribing to any of the events listed above, you will also start receiving webhooks for the following events automatically:

Error
Suspended
Disconnected

The webhook subscription API endpoints also allow you to manage your subscriptions (view all subscriptions, update or delete subscriptions).

📘

The IP address of the upSWOT server may need to be whitelisted on your side to receive the webhook requests.

Connection to callback URL is only allowed via the standard ports: 80 (HTTP) and 443 (HTTPS). The use of other ports will result in failed calls.

Users with the following roles are allowed to subscribe to webhooks:

Integration users

FI administrators

Global administrators.

With each subscription call, you may only subscribe to one event; you may still subscribe to multiple events under the same user and the same callback URL via multiple subscription requests for the respective events.

Webhook Retries

If a webhook call to a specific callback URL is unsuccessful (i.e., the callback URL does not respond with the HTTP 2XX status code), the upSWOT system will attempt to send the request again after a certain time interval. By default, there will be 5 attempts to send the request with an interval of 2 minutes; the number of attempts and the interval can be adjusted in the System Settings section in the Admin Panel (see Set up Retry Attempts and Intervals).

❗️
Once the retry limit is reached, the subscription to the event under the given callback URL will be canceled without any notification.

Webhook Payload

The webhook payload contains metadata, event data, and signature.

👍
Example

{  
  "Class": "DataConnection",  
  "MessageType": "RawData",  
  "Identifier": "RawData.f8e75a2b-4364-42f5-b52e-3e6505309196",  
  "Data": {  
    "SessionShareId": "f8e75a2b-4364-42f5-b52e-3e6505309196",  
    "CompanyId": "93e05dd4-6b87-4793-8975-38b81f5a1db6",  
    "AccountExternalId": null,  
    "ApplicationId": null,  
    "ServiceId": "2ce0ca85-5f6c-11e9-b797-080027653e25",  
    "ServiceName": "FreeAgent",  
    "CategoryName": "Accountancy",  
    "CategoryId": "2cc07dc1-5f6c-11e9-b797-080027653e25",  
    "Email": "[[email protected]](mailto:[email protected])",  
    "IssuedAs": "Manual",  
    "ModifiedOn": "2023-11-11T20:12:53.419897"  
  },  
  "Signature": "00dba385e120d0c221cf372077a5f55f371a0bd403f1b4b97aa5dd49886909d4"  
}

Metadata

The metadata properties contain the general details of the webhook request:

PROPERTY	TYPE	DESCRIPTION
`Class`	string	Type of the webhook request. `DataConnection` is the only class available currently.
`MessageType`	string	The event that the webhook request represents: - `RawData` - `NormalizedData` - `ReadyToUseData` - `Error` - `Suspended` - `Disconnected`
`Identifier`	string	Unique identifier of the data sharing event represented by the webhook request. This will be useful for distinguishing unique data-sharing events. This property is also used to calculate the webhook signature.

Event Data

The Data object contains the details of the respective data-sharing event:

PROPERTY	TYPE	DESCRIPTION
`SessionShareId`	string	Unique identifier of the data-sharing session.
`CompanyId`	string	Unique identifier of the SMB User’s company in the upSWOT system.
`CompanyExternalId`	string	Unique identifier of the client on your side. Typically available when Single Sign-On (SSO) is used.
`ApplicationId`	string	Unique identifier of the client's loan application. Available if the loan onboarding workflow was used with the data connection.
`ServiceId`	string	Unique identifier of the app from which the client shared their business data with upSWOT.
`ServiceName`	string	Name of the app from which the client shared their business data with upSWOT. Note: When building the logic for processing webhook requests on your side, it is strongly recommended not to use `ServiceName` for filtering, etc., as the names of the apps may be subject to change in future releases; instead, `ServiceId` should be used to maximize forward compatibility.
`CategoryId`	string	Unique identifier of the app category.
`CategoryName`	string	Category of the app from which the client shared their business data with upSWOT. Note: When building the logic for processing webhook requests on your side, it is strongly recommended not to use `CategoryName` for filtering, etc., as names of the categories may be subject to change in future releases; instead, `CategoryId` should be used to maximize forward compatibility.
`Email`	string	Email address of the primary user assigned to the company or email used with the loan application (if the loan onboarding workflow was used with the data connection).
`IssuedAs`	string	Origin of the data sharing session: - `Manual` – initiated by the user during the initial connection of the app - `Refresh` – initiated by the user when refreshing the data in the upSWOT Dashboard - `Permanent` – initiated by the permanent data update process - `Webhook` – initiated by the webhook request received from the app (typically banking aggregators) to notify of data updates on the app side - `SsoAuth` – initiated as part of the Single Sign-On (SSO) Authorization process. - `External` – created externally via upSWOT API - `Unknown` – data sharing session does not exist (this value is not expected in production environments)
`ModifiedOn`	datetime	The timestamp (in UTC) of the most recent modification in the respective data connection or data sharing session. Note: The value of `ModifiedOn` will remain unchanged in all retry webhooks (all retries have the original `ModifiedOn` value, not the timestamp when the retry was sent)

Signature

The Signature property of the webhook request helps ensure the authenticity of the sender and verify the integrity of the data received.

PROPERTY	TYPE	DESCRIPTION
`Signature`	string	Digital signature calculated as the hashed value of the request’s `Identifier` property using the SHA-256 algorithm with the private key configured in the upSWOT system.

The private key for a signature is defined in the SignedDataShareWebhookPrivateKey system setting in the Admin Panel (see Signature Private Key). You can generate the private key by yourself, or upSWOT can provide you with one.

Upon receiving a webhook request, you can calculate the expected digital signature and compare it with the one received in the Signature property of the request:

Take the Identifier property from the webhook body.
Use the private key configured in the upSWOT system to calculate the signature as the hashed value of the Identifier field. You can use any HMAC-SHA-256 generator tool, such as this one: https://www.devglan.com/online-tools/hmac-sha256-online.
If the signature calculated on your side matches the one received in the Signature property, the authenticity and integrity of the request are verified.

👍
Example

Identifier: RawData.f8e75a2b-4364-42f5-b52e-3e6505309196

Private Key: i7fSD04lWk9VoCdkjCwcXAeG9t71XQXmEaswPtUkxnERVQ2Zl+8sGqe/kRy0

Signature: 34a32ce6a872307ddcd5ac6ba61d4a93a026dfea66757a4ca491cfcc65ad1d46

Webhooks Configuration (System Settings)

Use the following System Settings in the upSWOT Admin Panel to configure webhooks behavior.

Enable Webhooks

Set the WebhooksEnabled system setting to true to enable webhooks, or to false to disable them.

Retry Attempts and Intervals

The WebhookMaxRetryAttempts setting defines the maximum number (inclusively) of attempts at delivering the webhook if the request is unsuccessful (i.e. if the callback URL does not respond with the HTTP 2XX status code). Once this limit is reached, the subscription to the event will be canceled automatically.
By default, the number of attempts is set to 5.

The WebhookRetryIntervalMinutes setting configures the time interval (in minutes) between retry attempts for webhook delivery after an unsuccessful attempt.
By default, the retry interval is set to 2 minutes.

Signature Private Key

The SignedDataShareWebhookPrivateKey setting configures the private key for calculating the webhook request’s digital signature using the SHA-256 algorithm.

Webhook Triggers (Event Types)

Webhook Subscriptions

📘

Webhook Retries

❗️

Webhook Payload

👍Example

Metadata

Event Data

Signature

👍Example

Webhooks Configuration (System Settings)

Enable Webhooks

Retry Attempts and Intervals

Signature Private Key

👍
Example

👍
Example