Getting started
Get Access to APIAuthenticationMaking your first requestGuides
Generate Doc X-RayGenerate Bank X-RayGenerate Financial X-RayGenerate ESG X-RayGenerate Manager X-RayConcepts
OverviewRequestReportsMediumDoc X-RayBank X-RayFinancial X-RayESG X-RayManager X-RayResources
API versioningWebhooksUploading a mediaAdd a creator to your requestTesting environmentOrganization & MembersSecuritySupportWebhooks
Asynchronous updates from October API
Webhooks are HTTP POST requests sent to a given URL each time certain events happen on the platform. They allow you to build deep integrations of our API into your organization system, track events or/and automatically trigger actions, without having to pull updates from our API on your side.
Events
When configuring a webhook you can use the October App to subscribe to some events (one or many). Each event is linked to a certain action that happened on the October platform, related to your organization.
The list of available events is:
Type | Description |
new_report | Triggered when a new report has been created |
Setup webhooks with the App
- Sign in to your October account.
- Click on the “Organization Settings” tab, then “Webhooks”
- If you do not see the “Webhooks” section, please contact your October representative.
- Click on the “Add Webhook” button, add your url, and select the events that will trigger it.
- The same webhook configuration can be used for one or more events (e.g:
new_report
) - Once the webhook is created, do a
GET /businesses/[business id]
HTTP request to list all your webhook configurations at the pathbusiness.settings.webhooks
- In the webhook configuration, you will find the keys needed to validate the webhooks you will receive
In the webhooks configuration tab of the app, add a new webhook with the events you want to subscribe to, and your endpoint URL. The secret key will be generated by October.
You can see all your added URLs in the webhooks configuration page:
Setup webhooks via Api only
The endpoint we will use is POST /businesses/:id
for this setup. These calls will create / update / delete webhook settings for your business.
A webhook setting is composed of a url
(where the callback should be sent), a list of events
and a key
(automatically generated by the October Api).
Adding a new webhook setting consist of sending an Json object including a list of events and an url.
{
"events": ["update_request"],
"url": "https://test.fr",
}
This webhook setting is stored in the settings.webhooks
array field of your business, with a generated key
.
Here is a list of examples HTTP post requests bodies to create / add / delete webhooks settings for your business :
Create first webhook setting
{
"settings": {
"webhooks":[
{
"events":["update_request"],
"url":"https://test.fr",
},
]
}
Example response sent by the api
{
"business": {
"code": {
"type": "siren",
"id": "123456789"
},
"id": "615ec1280906c5118dea77e6",
"name": "Borrower partner business",
"registrar": {},
"settings": {
"maxMonthlyRequests": 20,
"webhooks": [
{
"events": ["update_request"],
"url": "https://test.fr",
"key": "e4d1a4233b4cbe0473d44de1716e1065"
},
]
},
"creator": "615ec11a0906c5118dea77e4",
"meta": {},
"type": "partner"
}
}
You can add a new webhook setting to the existing list of webhook settings
{
"settings": {
"webhooks":[
{
"events":["update_request"],
"url":"https://test.fr",
"key":"4338b9437fb5c91aba507fff6a27b017"
},
{
"events":["new_offer", "update_offer"],
"url":"https://test2.fr",
"key":"9e60c8e60e6983b1c7626558bfceeb43"
}
]
}
}
Delete the first webhook setting by simply removing it from the list of settings
{
"settings": {
"webhooks":[
{
"events":["new_offer", "update_offer"],
"url":"https://test2.fr",
"key":"9e60c8e60e6983b1c7626558bfceeb43"
}
]
}
}
Content of the webhooks notifications
The webhook is a JSON object sent to you with an HTTP POST request.
The HTTP headers contain:
- the content type of the body, that is always JSON
- the timestamp of the request sending time
- the hash of the body + timestamp, using the secret key generated by the October API (when configuring the webhook). For more information, see Security.
The body of the webhook contains:
event
, the type of the event,- one or many IDs of the resources related to this event
- a
diff
object, if the event is related to an update with: - the updated field in
property
- the new value in
after
In case of a newly created resource, the webhook contains only the resource ID.
In case of a resource update, the after
field contains the new value, following the formats defined in the Models part of the API documentation.
"headers": {
"Content-Type": "application/json",
"X-O5R-HASH": "xxx", // (timestamp + body) hashed with the webhook key
"X-O5R-TIMESTAMP": "1632996186011" // webhook sending timestamp
},
"body": {
"event": "update_request" | "new_offer" | "update_offer",
"requestId": String | undefined,
"offerId": String | undefined,
"diff": {
"property": "status" | "stage" | "requirements",
"after": Any // updated object
} | undefined
}
{
"event": "update_request",
"requestId": "1b9e20b6hexb81w0133ahe92",
"diff": {
"property": "status",
"after": "accepted"
}
}
Security
To authenticate webhook requests and to make sure that October is actually sending the webhook, it is important to use the security headers provided with each notification.
The headers contain 2 security keys, X-O5R-HASH
and X-O5R-TIMESTAMP
:
X-O5R-HASH
: timestamp + webhook body, hashed with the SHA256 algorithm, using the secret key (provided in the webhook settings).X-O5R-TIMESTAMP
: Timestamp created when sending the message. You can use it to determine that theX-O5R-HASH
hashed body contains a matching timestamp, and refuse all webhooks not checking this condition.
Once the X-O5R-HASH
is validated with the X-O5R-TIMESTAMP
, you will be able to validate that the body of the webhook matches its hashed value.
This will prevent attackers from sending you fake notifications or content.
Validate the X-O5R-HASH
Hash (using the SHA256 Hmac algorithm) the timestamp and the body with the secret key (provided in the webhooks settings).
- ⚠️ The webhook body is stringified to create the hash
{
"event": "update_request",
"requestId": "1b9e20b6hexb81w0133ahe92",
"diff": {
"property": "status",
"after": "accepted"
}
}
Will be transformed into
'{"event":"update_request","requestId":"1b9e20b6hexb81w0133ahe92","diff":{"property":"status","after":"accepted"}}'
- Hash the timestamp and the body with the secret key using the SHA-256 Hmac algorithm
sha256Hmac(X-O5R-TIMESTAMP + strigifiedBody, secretKey)
Here an example of how you can do it:
const crypto = require('crypto');
const receivedHash = '134e8169151948be2b3a35ae09405b56c29917b8a8371d349ef162b0b1976982';
const receivedBody = '{"event":"update_request","requestId":"1b9e20b6hexb81w0133ahe92","diff":{"property":"status","after":"accepted"}}';
const receivedTimestamp = '1647937499151';
const secretKey = 'c35d3a6f69d7dfb55c2b19364039aa14';
const hash = crypto.createHmac('sha256', secretKey).update(receivedTimestamp+receivedBody).digest('hex');
console.log(hash); // Prints 134e8169151948be2b3a35ae09405b56c29917b8a8371d349ef162b0b1976982
console.log(hash === receivedHash) // Prints true
Retry policy
Webhooks sent by October have a retry policy to handle transient failures when it tries to connect to your service.
October will try to resend the webhook 10 times by default with 5mn of delay, this behavior changes depending on the status code in the response you send back to our call:
200
status: you received the webhook successfully, no retry.40x
/500
status: there was an error with the webhook, October will retry (up to 10 times by webhook).
← Previous
On this page
- Webhooks
- Events
- Setup webhooks with the App
- Setup webhooks via Api only
- Create first webhook setting
- You can add a new webhook setting to the existing list of webhook settings
- Delete the first webhook setting by simply removing it from the list of settings
- Content of the webhooks notifications
- Security
- Validate the X-O5R-HASH
- Retry policy