Gateway Hub ["Geneos"]
["Geneos > Gateway Hub"]["Technical Reference"]

Webhooks

Overview

The Webhooks page allows you to configure the publishing of events data to external applications using API calls. You can connect to multiple APIs or applications by creating multiple Webhooks. This allows you to easily build bespoke integrations with your preferred tools.

This page also displays the status of all existing Webhooks and allows you to create new Webhooks.

Webhook configuration

To configure Webhooks, you must have administrator permissions for Gateway Hub.

To create a Webhook, click New Webhook. This opens the Webhook configuration page. You must enter the details of the external applications API. Gateway Hub will send events by performing an HTTP request.

Field Description
Name Name of the external application.
URL URL of the target API.
Method HTTP request method. Choose from POST or PUT.
Batch size

Number of events to send in each batch. Setting this to 0 disables batch publishing.

Default: 0

   

Enable or disable this Webhook using the toggle labelled Enable Webhook.

Webhook requests

Once a Webhook is configured Gateway Hub will perform requests with specified method. The payload of a request has a form similar to the following:

{
  "version": "1.0",
  "type": "event",
  "primaryKey" : "1/snooze",
  "data": 
    {
      "timestamp": "2019-08-26T09:34:45.256Z",
      "entityId": 1,
      "attributes": { ... },
      "type": "snooze",
      "event": {  }
    },
  "operation": "update"
}

Requests made by Webhooks have the following fields:

Field Description
version Data schema version. This version will only change if Gateway Hub changes it's publishing format to one that is not backwards compatible.
type

Payload type. The available options are:

  • event

primaryKey String that uniquely identifies the source.
data.timestamp Timestamp of this event.
data.entityId Gateway Hub entity ID this event refers to.
data.attributes Attributes of the Gateway Hub entity specified by the data.entityId field.
data.type Type of event.
data.event Raw event payload provided by Gateway.
operation Gateway operation type.
   

Authentication

The Authentication section allows you to configure authentication for the target API. The options are:

  • (default) Basic
  • None

If you select Basic, then you must set the following options:

Field Description
User Username used to connect to the API.
Password Password used to connect to the API.
   

Attributes

The Attributes section allows you to specify the information included in the events data.

Each event corresponds to a change in the state of an entity. You can specify which attributes of an entity should be included in the event data.

To include data about an attribute:

  1. Click add button.
  2. Select an attribute from the drop-down list.

Filtering

Filtering allows you to publish a smaller subset of your data. This can considerably reduce the storage and processing requirements of a downstream application.

You can use one or more filter predicates to filter the data by message type and entity query. A record is published if it meets any of the includes conditions. However, a record is not published if it meets any of the excludes conditions even if it also meets an includes condition.

For example, given the configuration below, all metrics and events will be published for Entities where Application = Fidessa except where Department = Fixed Income

Include/Exclude Message type Entities
Include Events Application = Fidessa
Include Metrics Application = Fidessa
Exclude All Department = 'Fixed Income'

You can specify filters on entities using the basic or advance menus:

  • The basic menu allows you to select entities by specifying an attribute and a value.
  • The advanced menu allows you to input a filter manually.

Note: Events and metrics data are treated independently, some Gateway Hub components only use events data.

To create a filter using entities:

  1. In the Filtering section, click New Filter. This opens the New filter window.
  2. In the Entities field, click add button.
  3. Select the attribute and its corresponding value. The entities matching the query generates a value.
  4. Click Add Filter.

Snapshots

You can create a snapshot of the latest events in order to reset an external system in the event of a failure.