Webhook integrations

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

JSON payload must now follow the official specifications (see here for more info), this means that if you had payloads with single quotes instead of double quotes you must fix them. Otherwise webhook action will fail.

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

PHP extention curl is required for webhook integrations

• 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 occurs, response callback is not called.
• Google Chat action only works with Google Workspace (paid version)

Use the Standard installation process for this extension.

Some configuration parameters are available for the extension

'combodo-webhook-integration' => array (
    'certificate_check' => true,
    'prefer_asynchronous' => false,
    'timeout' => 5,
),

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.

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 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.

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

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

Go to the “Slack API” page 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.

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

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. It is possible to use $this placeholder. For instance if the webhook is triggered by a ticket $this→team_id→attribute$

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

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

Sending notifications to your Microsoft Teams workspace requires 3 steps:

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

Microsoft Teams full documentation is available here

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

In Teams, open the chanel you want to create to webhook for. Then click on “Connectors” in the top right menu.

Look for “Incoming Webhook” and click “Configure” to configure a new one.

Give a name and optionally an image that will be displayed for messages of that webhook. \ Once added, copy the webhook URL and go back to your iTop

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

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. It is possible to use $this placeholder. For instance if the webhook is triggered by a ticket $this→team_id→attribute$

In your iTop, create a new Microsoft Teams notification action.

• Select the connection created in the previous step
• Prepare the message to send in Microsoft Teams
• 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

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

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

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.

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. It is possible to use $this placeholder. For instance if the webhook is triggered by a ticket $this→team_id→attribute$

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

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

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

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.

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. It is possible to use $this placeholder. For instance if the webhook is triggered by a ticket $this→team_id→attribute$

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

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

Note: This is step is optional is you already configured a webhook to the same desired remote iTop.

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

• Application type: Just for documentation / information
• Environment: Just for documentation / information
• URL: The URL to the remote iTop, it should look like <ITOP_APP_ROOT_URL>/webservices/rest.php. It is possible to use $this placeholder. For instance if the webhook is triggered by a ticket $this→team_id→attribute$
• API version: API version of the remote iTop you want to use.
• Auth. user: Remote iTop login to use
• Auth. passwd: Remote iTop password to use

In your iTop, create a new iTop webhook call action.

• Select the connection created in the previous step
• Prepare the JSON payload to be used and execute on the Remote iTop. See REST/JSON Documentation for details

Description of the available attributes

Then you just have to link this Action to the triggers that will call it. For instance when my ticket is entering state “pending”, we create a ticket in a remote iTop

In the JSON Data field, you can use the $this placeholder to make reference to attribute corresponding to the element that triggered the event.

For instance $this→title$

If the construction of your payload requires specific processing you will have to use a method defined in “Prepare payload callback”

This chapter has to be use if you want to connect to an application using directly its REST/JSON API, and if it is not already preconfigured in iTop like Slack, Google or Rocketchat

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 url corresponding to the REST API call you want to execute . It is possible to use $this placeholder. For instance if the webhook is triggered by a ticket $this→team_id→attribute$

In my example above, we use a web service to create an issue in MantisBT

In your iTop, create a new Webhook call (generic) action.

• Select the connection created in the previous step
• define the header to be sent to the web server. There are used often to define the credential to be used in the Authorisation
• Prepare the JSON payload to be used and execute on the Remote iTop. see REST/JSON Documentation for details

Description of the available attributes

Then you just have to link this Action to the triggers that will call it. For instance when my ticket is entering state “pending”, I create a ticket in a ManitBT

In the fields JSON Data, you can use the $this placeholder to make reference to attribute corresponding to the element that triggered the event.

For instance $this->title$

If the construction of your payload requires specific processing you will have to use a method defined in “Prepare payload callback”

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

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

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)

Only in iTop 3.0+, if you configure webhooks to be sent asynchronously, you can also configure retries on error. This can be done using the async_task_retries configuration parameters of the application. Class names to use can be found in the “Datamodel Viewer” in your iTop backoffice.