How to set up webhooks in iOFFICE
iOFFICE clients have a need to track changes in their data. Our solution is to implement a way for clients to set up a selection of data changes to track and send to a specified URL, webhooks. By creating a webhook in iOFFICE and a server to receive changes, a client can track the selected changes to their data. Their are two prerequisites that need to be in place in order to utilize webhooks. The first pre-requisite is Site Administrators are needed to add the webhooks within iOFFICE. The second pre-requisite is a server to receive the webhook message.
Accessing Webhooks
1. To access webhook configuration, select the Admin icon on the menu ribbon on the left-hand side of the screen to display iOFFICE admin tools.
2. Next click Marketplace to display the Marketplace admin tools,
3. Click the Webhooks tab to access the tool
Adding a Webhook
1. First Click the + Create Webhook at the upper right-hand corner.
2. Click the Payload URL field and enter the Payload URL.
3. Click the input field for the Secret key and enter the credentials.
4. Select the Event type and Method. There are 140 points of data that can be specified. Use the toggle to turn off Send Me Everything, and a list of data points will display. Select the data you would like to share by clicking the checkbox next to the data point.
The Payload URL is the URL that will receive the webhook message. The Secret is a password to use when sending the message. This will be used like a salt and hashed with the payload so that the source can be verified. There are different types of Secrets that can be setup which are seen in the definitions below:
Methods | Description |
---|---|
Payload URL | The URL which will receive the webhook message. |
Secret | A Secret to use when sending the message. This will be used like a salt and hashed with the payload so that the source can be verified. |
Event | Track the type of change, whether it is one of the following: Create, Update, Delete, Archive. |
Method | Select whether you want to receive the message as an HTTP GET or HTTP. |
Entities | If the Send Me Everything is not toggled, then specific Entities or Data points can be selected for tracking. |
Steps to add Service
Once you setup your webhooks within iOFFICE, you will need a server to receive the events and process them in some way. An HTTP server is required with an exposed endpoint that is able to receive GET or POST requests. Below is an example of what this would look like for using the GET and POST.
Method
Entity that has change - Agreement
Event that is taking place - CREATE
Id of the entity - 25
When configuring webhooks in iOFFICE, there are two options on how to receive the messages.
GET - This will send a GET request to your service with the entity type, event type, and entity id as part of the path. With the example given below, you would receive a GET request at:
https://www.webhookexampleioffice.co...E/Agreement/25
POST - This will send a POST request to your service with the entity type, event type, and entity id as part of the body. With the given example, you would receive a POST request at:
https://www.webhookexampleioffice.co...E/Agreement/25
With the JSON body as:
{
"eventType":"CREATE",
"entityType":"Agreement",
"entityId": 25
}
Each request has a header, named as x-ioffice-signature, associated with it to verify the authenticity of the request. This header includes the hashed string to which you can verify the request by hashing the payload/path with your secret.
Secret
When sending a message, a header will be included, named as x-ioffice-signature, that will have a value equal to the HMAC-256 hash of the payload/path with a: separating each part of the message with your secret as the key.
With the given example under method, a hashable string would look like the following:
CREATE:Agreement:25
This is then run through the HMAC-SHA265 algorithm, with the secret setup in iOFFICE as the key.
Node.js example
>> const c = require('crypto');
>> c.createHmac('sha256', 'mySecret').update('CREATE:Agreement:25').digest('hex')
This will create a hash 6206491ddab1218e7d6a9c8b3fbaa43da7858ee678dc6cd53a4dcabf0216568e
The webhook message will have the above hash as a header. When receiving the message on your service, you will need to run the payload.
{
"eventType":”CREATE”,
"entityType":”Agreement”,
"entityId": 25
}
The parameters from the path /CREATE/Agreement/25 through your own implementation of the HMAC-SHA256 algorithm and compare that hash to the hash included in the header to verify the origin of the message.