Set up Webhooks in Eptura Workplace

Add a Webhook

1. Navigate to Admin > Marketplace > Webhooks.
2. Click the Create Webhook button. The Create Webhook form displays.
3. In the Payload URL field and enter the Payload URL. The Payload URL is the URL that will receive the webhook message.
4. In the Secret field, enter the secret key.  The secret key is a password to use when sending the message. 

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.

5. From the Event drop-down, select either Create, Update, Delete, or Archive. 
6. From the Method drop-down, select either Post or Get.
7. 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. To select the specific data then check the data point's checkbox.

Add Service

After you setup your webhooks within Eptura Workplace, 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 you configure a webhooks in Eptura Workplace, 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.com/v1/iofficewebhook/CREATE/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.com/v1/iofficewebhook/CREATE/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 Eptura Workplace 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.