Notifications/Webhooks¶
It is possible to subscribe to notifications to receive status updates about the proposals you have submitted. This is a more efficient way of getting updates than polling for changes on a schedule.
Notifications will be sent by Siemens Financial Services (SFS) in certain scenarios:
- When the credit decision changes; if the deal isn't initially auto-accepted, the credit decision is subject to change when it has been assessed by our under-writers (DECISION_RECEIVED)
- When the overall status of the proposal changes; for example when the contract has been activated (CREDIT_STATUS_CHANGED)
Hint
You will need the ability to receive incoming API requests to make use of the notification service.
Setting up initial notification service¶
To be able to receive notifications from SFS, you first need to register your notification endpoint. There are three endpoints under the heading 'NotificationEndpoints' that allow you to do this.
This is a single URL which will receive notifications about all proposals you subscribe for:
{
"apiKey": "sdJH67ZZHHJj23dsf",
"basePath": "https://myb2bhost.de:8080/b2b/api/siemart"
}
| Name | Type | Required | Description |
|---|---|---|---|
| apiKey | string | false | A unique key that will be sent back to you in the request header, as X-API-KEY |
| basePath | string | true | The URL where POST requests from SFS will be sent. You should register your base path; we will add '/notifications' to the URL. |
Hint
- You only need to perform this step once.
- The URL you register is the base URL. We will add '/notifications' to this when sending the notification. For example if you register https://myb2bhost.de:8080/b2b/api/siemart, we will send notifications to https://myb2bhost.de:8080/b2b/api/siemart/notifications.
There are also PUT and DELETE requests that allow you to modify the above information, or cancel notifications overall.
Subscribing to proposal notifications¶
Once you have completed the step above, you need to subscribe to notifications for each proposal you are interested in.
A separate POST request needs to be made to subscribe to each event type.
Example:
The response to this will be a UUID - this is a unique ID identifying that combination of proposal ID and event type.
Important
Save this UUID in your system, as when a notification is sent to you, you will need the UUID to identify it.
Handling notifications¶
When a notification that you have subscribed to is triggered, a POST request will be sent to the URL you registered. The UUID will be included in the 'notification-uuid' query parameter.
For example:
https://myb2bhost.de:8080/b2b/api/siesmart/notifications?notification-uuid=ee3f630f-89d1-4c4b-8ed0-60e3cb7a1ab5
The body of the POST request will be empty.
If you registered an API Key as part of the initial registration, this will be included here as an X-API-KEY header.
The request that is sent to you doesn't contain any information about the proposal, or the event that triggered it, just the UUID.
You should then query the proposals endpoint to get the latest status.