Configuring the webhook v1 transport

The webhook v1 transport allows the probe to send the following types of HTTP requests to the target device:

loginRequest: This is sent after the OAuth access token request to log into the target system.
loginRefresh This is sent periodically to refresh the login on the target device.
logoutRequest This is sent before disconnecting from the target device.
resynchRequest This is sent to request an event resynchronization with the target device.
subscribeRequest This is sent to subscribe to received events from the target device as they are created.
subscribeRefresh This is sent periodically to refresh the event subscription on the target device.

The transport also enables the probe to create a callback URL to which the target server or an HTTP client can sed notifications using POST or GET requests.

Note: There are currently two webhook probe transports. For details of the differences between the two types, see Webhook probe transport types so that you can chose the most appropriate one for your environment.

Web Hook transport properties

The following table describes the properties in the restWebhookTransport.properties file.

Note: When using the Web Hook transport, you must specify values for the Host and Port properties in the message_bus.props file.

Table 1. Properties in the restWebHookTransport.properties file
Property name	Description
httpVersion	Use this property to specify the version of the HTTP protocol that the target system supports. The default is 1.1.
httpHeaders	Use this property to specify the HTTP header options to use in all HTTP requests. This property accepts a comma separated list of key-value pairs using the equals sign (`=`) as the value separator. For options that accept multiple values, use the double-quote (") character around the value and a use semi-colon (;) as the value separator; for example: `Keep-alive="timeout 30;max 10",Connection=Keep-alive` For the authorization header option, the credentials that follow the single whitespace after `Basic` are encoded as a Base-64 encoded string. For example, to authenticate with the username `Me`, and the password `MyPassword`, set the httpHeader property to Authorization=Basic Me:MyPassword. The probe passes this as an authorization header with every request. The default value is "". Note: The httpHeaders property sets the headers for all HTTP requests. However, you can override these global HTTP header options using the following properties: loginRequestHeaders loginRefreshHeaders logoutRequestHeaders resyncRequestHeaders subscribeRequestHeaders subscribeRefreshHeaders
responseTimeout	Use this property to specify how long (in seconds) the probe waits for a response from the target system before timing out. The default is 60 seconds.
loginRequestURI	Use this property to specify the URI that the probe uses to request a login.
loginRequestMethod	Use this property to specify the message type that the probe sends to request a login.
loginRequestContent	Use this property to specify any additional information that the probe sends with the login request.
loginRequestHeaders	Use this property to specify an HTTP header to send with all login requests. This overrides the global HTTP header options configured by the httpHeader property.
loginRefreshURI	Use this property to specify the URI that the probe uses to refresh the login on the target device.
loginRefreshMethod	Use this property to specify the message type that the probe sends to refresh the login on the target device.
loginRefreshContent	Use this property to specify any additional information that the probe sends with the login refresh request.
loginRefreshHeaders	Use this property to specify an HTTP header to send with all login refresh requests. This overrides the global HTTP header options configured by the httpHeader property.
loginRefreshInterval	Use this property to specify the interval (in seconds) that the probe leaves between successive login refresh requests. This can be disabled by setting it to "" or leaving it commented out. If set to a negative value or an valid value such as String, it will default to 60 seconds.
logoutRequestURI	Use this property to specify the URI that the probe uses to request a logout from the target device.
logoutRequestMethod	Use this property to specify the message type that the probe sends to request a logout from the target device.
logoutRequestContent	Use this property to specify any additional information that the probe sends with the logout request.
logoutRequestHeaders	Use this property to specify an HTTP header to send with all logout requests. This overrides the global HTTP header options configured by the httpHeader property.
resyncRequestURI	Use this property to specify the URI that the probe uses to request a resynchronization with the target system at startup. You can append the URI that you specify with this property with a query filter that limits the scope of the events that are returned by the request. Note: resyncRequestURI and resyncRequestMethod=GET can be used independently, together with httpversion and responsetimeout, to perform the resynchornization. However, either initialResync or resyncinterval must also be specified.
resyncRequestMethod	Use this property to specify the message type that the probe sends to request a resynchronization with the target system. Note: resyncRequestURI and resyncRequestMethod=GET can be used independently, together with httpversion and responsetimeout, to perform the resynchornization. However, either initialResync or resyncinterval must also be specified.
resyncRequestContent	Use this property to specify any additional information that the probe sends with the resynchronization request.
resyncRequestHeaders	Use this property to specify an HTTP header to send with all resynchronization requests. This overrides the global HTTP header options configured by the httpHeader property.
serverBasicAuthenticationUsername	Use this property to specify the webhook (server) basic authentication username.
serverBasicAuthenticationPassword	Use this property to specify the webhook (server) basic authentication password. This is used together with serverBasicAuthenticationUsername to support basic authentication for the server component and is used for client authentication using the HTTP Basic Authentication scheme. Both the serverBasicAuthenticationUsername and serverBasicAuthenticationPassword properties must be set to enable basic authentication. If these properties are set, the probe will accept HTTP requests with the correct credentials specified in the Authorization header. If the credentials do not match, the probe will reject the request with the error code: `401 Unauthorized`. An empty password is not supported. Note: You can encrypt the password using the nco_aes_crypt utility within Netcool/OMNIbus. The transport module only supports `AES_FIPS`, so you must use `-c AES_FIPS`.
subscribeRequestURI	Use this property to specify the URI that the probe uses to request a subscription to receive new alarms as they are created in the target system.
subscribeRequestMethod	Use this property to specify the message type that the probe sends to request a subscription to receive new alarms.
subscribeRequestContent	Use this property to specify any additional information that the probe sends with the subscription request.
subscribeRequestHeaders	Use this property to specify an HTTP header to send with all subscription requests. This overrides the global HTTP header options configured by the httpHeader property.
subscribeRefreshURI	Use this property to specify the URI that the probe uses to request a subscription refresh.
subscribeRefreshMethod	Use this property to specify the message type that the probe sends to request a subscription refresh.
subscribeRefreshContent	Use this property to specify any additional information that the probe sends with the subscription refresh request.
subscribeRefreshHeaders	Use this property to specify an HTTP header to send with all subscription refresh requests. This overrides the global HTTP header options configured by the httpHeader property.
subscribeRefreshInterval	Use this property to specify the interval (in seconds) that the probe leaves between successive subscription refresh requests. This can be disabled by setting it to "" or leaving it commented out. If it is set to a negative value or an valid value such as String, it will default to 60 seconds.
keepTokens	Use this property to specify a comma-separated list of the attributes that the probe extracts from the incoming JSON data. These data items can be used in token substitution throughout the runtime of the probe.
refreshRetryCount	Use this property to specify the maximum number of times that the probes sends a refresh request. If set to an invalid value such as a string or a value less than zero, it will default to zero and no limit is applied. The default is 0.
securityProtocol	Use this property to specify the security protocol to use when retrieving events from the REST API.
tokenEndpointURI	Use this property to specify the URI that the probe uses to obtain an access token for the target device. This is the path on the remote host to request an access token, for example: `tokenEndpointURI=/oauth/token` By default, this property is not set, which disables the OAuth token request; no access token request will be sent to the server.
basicAuthenticationUsername	Use this property to specify the basic authentication username that the probe should use in the authentication header to gain access to the target device.
basicAuthenticationPassword	Use this property to specify the password associated with the basic authentication username that the probe should use in the authentication header.
clientId	Use this property to specify the `Client ID` registered with the `Oauth` server. This parameter will be sent in the HTTP request-body. Leave this property empty if this should be omitted to use the `Basic Authentication` client authentication method.
clientSecret	Use this property to specify the `Client Secret` string registered to the clientId. This parameter will be sent in the HTTP request-body. Leave this property empty if this should be omitted to use the `Basic Authentication` client authentication method.
scope	Use this property to specify the level of access to the target server that the probe is requesting. You can specify a comma-separated list of scopes, for example: `scope=read,write`
webhookURI	Use this property to specify the path of the Web Hook URI on the local server into which the target device will POST notifications. This property can be set to a URL to specify the scheme (HTTP or HTTPS), port number, and path, for example: `webhookURI=/probe/webhook` or `webhookURI=http://hostname:80/probe/webhook` If only the path is specified, the HTTP(s) server will bind to the local port number specified in the Port property of the message_bus.props file. Make sure the local port is free. If unset or empty, the probe will generate a path. By default this property is set to `OFF`, the HTTP(s) server is disabled.
respondWithContent	Use this property to specify whether the probe includes the HTTP body received from the client HTTP request in the HTTP response. Set this property to `ON` to configure probe webhook to include the HTTP body. If set to `OFF_WITH_HTTP_200`, the probe will respond with `200 (OK)` for a successful request without a body in the response. The default is `OFF` and the probe will respond with `204 (No Content)` response code.
validateBodySyntax	Use this property to specify that the probe performs a JSON and XML syntax format check on the HTTP request body. The default is `ON`.
validateRequestURI	Use this property to specify whether the probe checks the URI paths. Set this property to `ON` to enable URI path check. Setting this property to `OFF` disables the URI check and the webhook will accept all HTTP request regardless of the path set. The default is `ON`.
idleTimeout	Use this property to specify the time (in seconds) to allow an idle HTTP client to be connected. When the timeout period has elapsed, the idle client is disconnected to free up resources. The default is `180`.

The following is an example of a restWebHookTransport.properties file:

# Example format of Web Hook properties file

#httpVersion=1.1
#httpHeaders=
#responseTimeout=60
#loginRequestURI=
#loginRequestMethod=
#loginRequestContent
#loginRequestHeaders=
#loginRefreshURI=
#loginRefreshMethod=
#loginRefreshContent=
#loginRefreshHeaders=
#loginRefreshInterval=
#logoutRequestURI=
#logoutRequestMethod=
#logoutRequestContent=
#logoutRequestHeaders=
#resyncRequestURI=
#resyncRequestMethod=
#resyncRequestContent=
#resyncRequestHeaders=
#subscribeRequestURI=
#subscribeRequestMethod=
#subscribeRequestContent=
#subscribeRequestHeaders=
#subscribeRefreshURI=
#subscribeRefreshMethod=
#subscribeRefreshContent=
#subscribeRefreshHeaders=
#subscribeRefreshInterval=
#keepTokens=
#refreshRetryCount=0
#securityProtocol=
#tokenEndpointURI=
#basicAuthenticationUsername=
#basicAuthenticationPassword=
#clientId=
#clientSecret=
#scope=
#webhookURI=OFF 
#respondWithContent=OFF
#validateBodySyntax=ON
#validateRequestURI=ON
#idleTimeout=180