How Webhooks Work
upSWOT system facilitates automatic HTTP requests (webhooks) sent to the subscribed listener URLs during the different stages (events) of 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 connected app.
- NormalizedData: the app data has been successfully normalized and structured.
- ReadyToUseData: data processing has been completed, and ready-to-use data (KPIs, Insights, benchmarks) has been calculated.
- Error: an error occurred during one of the data-sharing stages.
- Suspended: the user has suspended data updates for the app.
- Disconnected: the user has disconnected the app and deleted its previously shared data.
Webhook Subscriptions
To start receiving webhook requests, you must subscribe to one or several events using the webhook 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 subscription endpoints also allow you to manage your subscriptions (view all subscriptions, update, or delete subscriptions).
Note
- 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.
- 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 (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 five attempts to send the request with an interval of 2 minutes.
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]",
"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 | A unique identifier of the data-sharing event is represented by the webhook request. This will be useful for distinguishing unique data-sharing events. This property is also used to calculate the webhook's 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 | A unique client identifier is 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. |
| 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. |
| CategoryId | string | Unique identifier of the app category. |
| string | The email address of the primary user assigned to the company or the 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 (UTC) of the most recent modification in the respective data connection or data-sharing session. The value of the ModifiedOn will remain unchanged in all retry webhooks (all retries had the original modifiedOn value, not the timestamp when the retry was sent). |
Signature
The Signature property of the webhook request helps ensure the sender's authenticity and verify the integrity of the data received.
| PROPERTY | TYPE | DESCRIPTION |
|---|---|---|
Signature | string | The digital signature is 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 upSWOT Admin Panel. You can generate the private key by yourself, or upSWOT can provide you with one.
The same private key, configured in the same system setting, is also used by the previous versions of upSWOT webhooks.
Upon receiving a webhook request, you can calculate the expected digital signature and compare it with the one you 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. 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 you received in the Signature property, the authenticity and integrity of the request have been verified.
Example
Identifier: RawData.f8e75a2b-4364-42f5-b52e-3e6505309196
Private Key: i7fSD04lWk9VoCdkjCwcXAeG9t71XQXmEaswPtUkxnERVQ2Zl+8sGqe/kRy0
Signature: 34a32ce6a872307ddcd5ac6ba61d4a93a026dfea66757a4ca491cfcc65ad1d46