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:

 

Secrets

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.