Skip to main content
Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

REST Subscriptions (Webhooks)

  1. Last updated
  2. Save as PDF

Overview

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.

Endpoints_menu.png

To access the Endpoints section, you'll need the "Integration Administrator - Adapter" role.

Roles.png

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

  1. In barometerIT, create the webhook where you specify the HTTPS URL that the change events are published to.
  2. 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.

           

NOTE

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

Field name Description
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.

 

Auth Types

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.