REST Subscriptions (Webhooks)
In a REST Subscription, you specify an HTTPS URL to which entity change events will be published. This is the same stream to which barometerIT publishes the change events, which has been routed so that listeners can be added to it. These events are listed in the News and History sections and the Event Stream of barometerIT.
In the barometerIT user interface, REST subscriptions can be found in the Administer > Endpoints section.
To access the Endpoints section, you'll need the "Integration Administrator - Adapter" role.
One example of how you could use a REST subscription is to accumulate data into a SQL database for custom reporting.
A change event is generated and published for every user contribution and automated edit that is performed in barometerIT. Edits include the following:
- creation, deletion and updating of entity records
- addition and removal of associations
- changes to standard fields and custom fields
The content of each message that is posted to the subscriber is in JSON format and includes:
- details of the edit (the type of edit, user who performed the edit, the status of the field or association before and after the edit)
- state of the object after the edit , including basic information and custom fields
- BN identity of the object, as well as the BN keys for all Option List selections, and so on.
Configuring REST subscriptions
To configure a REST subscription, you must
- In barometerIT, create the webhook where you specify the HTTPS URL that the change events are published to.
- Configure the subscriber to receive the content from the JSON messages that are published.
Creating a webhook in barometerIT
In barometerIT you must set up the Webhook where you specify the URL that the change events for a specific entity will be published to.
You need the Settings Administrator role to create a Webhook.
On the main menu, click Administer > Webhooks.
In the Webhooks view, click Create Webhook.
Create Webhook view options
|Name||Name of the Webhook|
|Type||Select the "Webhook" type|
|Description||Description of the Webhook|
|Endpoint URL||HTTPS URL of the subscriber|
|Event Type||The entity whose change events are published.|
|Content Type||Content type of the HTTPS request to be sent to the endpoint URL.|
|Auth Type||None, Basic, SSL|
|Credential 1||(Basic Auth) Username or (SSL) Subscriber's public cert|
|Credential 2||(Basic Auth) Password or (SSL) Publisher's public CA|
|Is Enabled||When Yes is selected, the Webhook is activated and change events are published to the endpoint URL.|
There are three auth types for REST subscriptions.
- None: We send the message to the endpoint without any authorization information.
- Basic: We send the message to the endpoint with a Basic Auth String in the request's Authorization header.
- SSL: We send the message to the endpoint with our public certificate and the subscriber's public certificate as a trusted certificate.
The SSL auth type is the most complex, but it's also the most secure. On the webhooks edit page, if SSL Auth is selected, you'll see two text fields. The first field is editable and should contain the Subscriber's public certificate. The second field will contain the Publisher's (barometerIT) Certificate Authority (CA) public cert. The CA public certificate should be added to the Subscriber's list of trusted Certificate Authorities.