Webhook integrations

name:
Webhook integrations
description:
Add webhook actions to integrate with 3rd-party apps when triggers are activated
version:
1.0.0
release:
2021-12-03
itop-version-min:
2.7.0
code:
combodo-webhook-integration
state:
stable
diffusion:
iTop Hub

Features

Allow outgoing webhooks via new actions on any existing triggers

  • send chat notifications to Google Chat, Rocket.chat & Slack, with the same placeholders as email notification.
  • replicate / mirror part of an object on another itop, through a simple configuration in json in an action and update local triggering object with remote information
  • call any third party application offering webservices

Revision History

Version Release Date Comments
1.0.0 2022-01-05 First version

Prerequisites

You need to be familiar with notifications in iTop, see here for more information.

Limitations

  • Webhook actions do not work with the TriggerOnLogUpdate trigger as it is restricted by “email-reply” to email actions only.
  • If asynchronous sending, total request cannot exceed 64MB when serialized, so URL + headers + payload should not excess 60MB (eg. if sending attachments).
  • If network error, response callback is not called.
  • Google Chat action only works with Google Workspace (paid version)

Installation

Use the Standard installation process for this extension.

Configuration

Some configuration parameters are available for the extension

'combodo-webhook-integration' => array (
    'certificate_check' => true,
    'prefer_asynchronous' => false,
    'timeout' => 5,
),
Parameter Type Description Default Value
certificate_check bool Whether the remote app certificate should be verified during connection. Set to false if connecting with non HTTPS servers. true
prefer_asynchronous bool Whether the webhook calls should be asynchronous or not, meaning that they will be sent by the CRON job. false
timeout integer Number of seconds before the connection timeout. 5

Usage

This extension does nothing out of the box, until you have created Remote application connections and Webhook actions to send data to third-party apps.

Remote application connections

Available in the “Configuration > Integrations” menu, remote application connections are the repository of endpoints to the third-party applications you want to integrate with. They will be used by the Webhook actions.

Here is an example for a Slack connection. The “application type” is a typology that has no impact it is just to ease filtering / documentation of all the connections.

Webhook actions

Webhook actions works like any other email actions:

  • Choose a destination (Remote application connection)
  • Link the desired Triggers
  • Configure the message / data to send

Out of the box, 5 new type of actions are available:

  • Slack notification to send a message to a Slack channel / user
  • Rocket.Chat notification to send a message to a Rocket.Chat channel / user
  • Google Chat notification to send a message to a Google Chat channel / user
  • iTop webhook call to call the standard REST/JSON API of another iTop
  • Webhook call (generic) to call any third-party webservices

Note: All “app-oriented” actions are based on the generic one but they hide all the complexity of generating the request (headers, payload, …) so you can focus on the content you want to send.

Tutorials

The following tutorials are based on the apps automation processes at the time this documentation was written. Keep in mind that they may change some parts of the processes / GUIs making this tutorials outdated. In that case follow their documentations directly and contact us so we reflect changes here.

Slack notifications

Sending notifications to your Slack workspace requires 4 steps:

  • Create your own “Slack app” (necessary only once)
  • Add an “incoming webhook” to the Slack app (necessary only once per channel / user you want to send notifications to)
  • Add this webhook as a Remote application connection in iTop (necessary only once like above)
  • Add the Slack notification action in iTop

Slack full documentation is available here

1. Create your own "Slack app"

Note: This step is optional if you already configured a Slack app.

Go to the “Slack APIpage and click on the “Create new app” button.

Configure it properties if you want, this step is optional but adding a custom icon and name brings a very nice touch to it.

2. Add an "incoming webhook" to the Slack app

Note: This step is optional if you already configured a webhook to the same desired channel / user.

On your app properties page, click on “incoming webhooks” in the left menu.

If not already done, activate the incoming webhooks.

Then click on “Add a new webhook to Workspace” and select its destination (a channel or a user).

Once added, copy the webhook URL and go back to your iTop

3. Add a "Remote application connection" in iTop

Note: This is step is optional is you already configured a webhook to the same desired channel / user.

In your iTop, create a new Remote application connection and fill the attributes:

  • Application type: Just for documentation / information
  • Environment: Just for documentation / information
  • URL: The webhook URL retrieved from the previous step

4. Add a "Slack notification" action in iTop

In your iTop, create a new Slack notification action.

  • Select the connection created in the previous step
  • Prepare the message to send in Slack
  • Choose some extra options (hover on their labels to have details on their purpose)
  • Link at least one Trigger like for any other action

Description of the available attributes

Slack notification Purpose
Name free text to identify this particular notification
Status To dis-activate this notification
Language Just for documentation / information
Connection This reference the URL, connection method,… to use for this notification
Test connection This reference the URL, connection method,… to use for this notification when in Test status
Message Text which will be written in Slack. You can use standard Notification placeholders
Attributes from Display additional attributes below the message. Possible values List / Slack
List will displays the standard list of attributes of the object triggering the notification.
Slack supposes that a slack XML tag is defined under presentation to specify the fields to display
User info. Display user information (full name) below the message. Possible values: Yes / No (default)
Modify button Include a button below the message to edit in iTop the object which has triggered the message. Possible values: Yes / No (default)
Delete button Include a button below the message to delete in iTop the object which has triggered the message. Possible values: Yes / No (default)
Other actions buttons Include transitions available in the current state below the message. Possible values: Yes / Specify / No (default)
Other actions codes Specify which transitions to include as buttons below the message. Should be a comma separated list of the stimuli codes (eg. ev_reopen, ev_close)
Prepare payload callback PHP method to prepare payload data to be sent during the webhook call. (See How to customize the sent payload)
Process response callback PHP method to process the webhook call response. (See How to process the response)

5. Test the notification

In the following example, the action is triggered by a log update on a User request.

Rocket.Chat notifications

Sending notifications to your Rocket.Chat application requires 3 steps:

  • Add an “incoming webhook” to the Rocket.Chat app (necessary only once per channel / user you want to send notifications to)
  • Add this webhook as a Remote application connection in iTop (necessary only once like above)
  • Add the Rocket.Chat notification action in iTop

Rocket.Chat full documentation is available here

1. Add an "incoming webhook" to the Rocket.Chat app

Note: This step is optional if you already configured a webhook to the same desired channel / user.

With an administrator account, open the “Administration” menu then the “Integrations” section and create a new “Incoming” integration.

Enable it and fill at least the following:

  • Post to Channel: Where you want to send notifications. Don't forget to start with “#” or “@” depending on if its a channel or user.
  • Post as: ID of the user that will be used to send the notification, must be a valid / existing one.
  • Alias, Avatar URL and Emoji allow you to override the corresponding attributes of the “Post as” user.

Once created, copy the “Webhook URL” and go back to your iTop instance.

2. Add a "Remote application connection" in iTop

Note: This is step is optional is you already configured a webhook to the same desired channel / user.

In your iTop, create a new Remote application connection and fill the attributes:

  • Application type: Just for documentation / information
  • Environment: Just for documentation / information
  • URL: The webhook URL retrieved from the previous step

3. Add a "Rocket.Chat notification" action in iTop

In your iTop, create a new Rocket.Chat notification action.

  • Select the connection created in the previous step
  • Prepare the message to send in Rocket.Chat
  • Choose some extra options (hover on their labels to have details on their purpose)
  • Link at least one Trigger like for any other action

Description of the available attributes

Rocket.Chat notification Purpose
Name free text to identify this particular notification
Status To dis-activate this notification
Language Just for documentation / information
Connection This reference the URL, connection method,… to use for this notification
Test connection This reference the URL, connection method,… to use for this notification when in Test status
Message Text which will be written in Rocket.Chat. You can use standard Notification placeholders
Alias Overrides for this specific action only, the Alias value of the webhook as defined in Rocket.Chat. You can use standard Notification placeholders
Image avatar Overrides for this specific action only, the Image avatar value of the webhook as defined in Rocket.Chat. You can use standard Notification placeholders
Emoji avatar Overrides for this specific action only, the Emoji avatar value of the webhook as defined in Rocket.Chat. You can use standard Notification placeholders
Prepare payload callback PHP method to prepare payload data to be sent during the webhook call. (See How to customize the sent payload)
Process response callback PHP method to process the webhook call response. (See How to process the response)

4. Test the notification

In the following example, the action is triggered by a log update on a User request.

Google Chat notifications

Sending notifications to your Google Chat application requires 3 steps:

  • Add an “incoming webhook” to the Google Chat app (necessary only once per channel / user you want to send notifications to)
  • Add this webhook as a Remote application connection in iTop (necessary only once like above)
  • Add the Google Chat notification action in iTop

Google Chat full documentation is available here

1. Add an "incoming webhook" to the Google Chat app

Note: This step is optional if you already configured a webhook to the same desired channel / user.

Open the Space for which you want to add the webhook and click on “Manage webhooks”

Give it a name, save, copy the URL and go back to your iTop instance.

2. Add a "Remote application connection" in iTop

Note: This is step is optional is you already configured a webhook to the same desired channel / user.

In your iTop, create a new Remote application connection and fill the attributes:

  • Application type: Just for documentation / information
  • Environment: Just for documentation / information
  • URL: The webhook URL retrieved from the previous step

3. Add a "Google Chat notification" action in iTop

In your iTop, create a new Google Chat notification action.

  • Select the connection created in the previous step
  • Prepare the message to send in Google Chat. Mind that only plain text is supported for now.

Description of the available attributes

Rocket.Chat notification Purpose
Name free text to identify this particular notification
Status To dis-activate this notification
Language Just for documentation / information
Connection This reference the URL, connection method,… to use for this notification
Test connection This reference the URL, connection method,… to use for this notification when in Test status
Message Text which will be written in Rocket.Chat. You can use standard Notification placeholders
Prepare payload callback PHP method to prepare payload data to be sent during the webhook call. (See How to customize the sent payload)
Process response callback PHP method to process the webhook call response. (See How to process the response)

4. Test the notification

In the following example, the action is triggered by a log update on a User request.

iTop webservices call

FIXME

Advanced

How to call another third-party app

FIXME

How to customize the sent payload

if standard options of a webhook action are not flexible enough or if your payload structure must be built dynamically, use the the Prepare payload callback attribute of the action. For this you can use 2 types of methods:

  • From the triggering object itself (eg. UserRequest)
    • Method must be public, arguments must not be passed. Example: $this->XXX
    • Arguments that will be passed automatically: $aContextArgs, $oLog, $oAction
  • From any PHP class
    • Method must be static AND public. Name must be name fully qualified (mind the “\”), arguments must not be passed. Example: \SomeClass::XXX
    • Arguments that will be passed automatically: $oObject, $aContextArgs, $oLog, $oAction
Argument Type Description
$oObject DBObject Only for static methods. The object that triggered the action
$aContextArgs array Context arguments used for notification placeholders
$oLog EventNotification Log object that will be displayed in the “Notifications” tab of the triggering object
$oAction ActionWebhook Webhook action activated by the Trigger

IMPORTANT: If set, the attributes of the action that would normally make the payload will be ignored (eg. message, payload, additional elements, …).

How to process the response

If you want to process the response of the webhook call, use the Process response callback attribute. You can use 2 types of methods:

  • From the triggering object itself (eg. UserRequest)
    • Method must be public, arguments must not be passed. Example: $this->XXX
    • Arguments that will be passed automatically: $oResponse, $oAction
  • From any PHP class, must be static AND public. Name must be name fully qualified. Example: \SomeClass::XXX
    • Method must be static AND public. Name must be name fully qualified (mind the “\”), arguments must not be passed. Example: \SomeClass::XXX
    • Arguments that will be passed automatically: $oObject, $oResponse, $oAction

Note that $oResponse can be null in some cases (eg. request failed to send)

Argument Type Description
$oObject DBObject Only for static methods. The object that triggered the action
$oResponse \Combodo\iTop\Core\WebResponse Context arguments used for notification placeholders
$oAction ActionWebhook Webhook action activated by the Trigger
extensions/combodo-webhook-integration.txt · Last modified: 2022/01/13 09:31 (external edit)
Back to top
Contact us