Settings

HipChat (On-Prem) Integration

Introduction to HipChat Integration

LogicMonitor has a variety of pre-built integrations for common ticketing and team collaboration systems such as ServiceNow and Slack, but the on-premises version of HipChat (i.e. hosted in your data center rather than hosted by Atlassian as a SaaS) is not currently one of them. But this needn't be a barrier; LogicMonitor’s custom HTTP delivery integrations can be configured to deliver alerts to your self-hosted version of HipChat.

Note: LogicMonitor does offer a pre-built integration for the SaaS version of HipChat that is hosted by Atlassian. If this is the version you would like to integrate with, see HipChat (SaaS) Integration.

A good use of this type of integration is to both avoid email alert overload and to increase responsiveness to an alert. In fact, the Technical Operations team at LogicMonitor uses just such a workflow. Our internal setup delivers all alerts to a HipChat room specifically created for monitoring messages. ERROR and CRITICAL alerts (i.e. any that would trigger an SMS to the on-call engineer) go to the "TechOps" HipChat room, where all Technical Operations engineers reside.
 While the on-call engineer will always receive an SMS for ERROR and CRITICAL alerts, other engineers are able to see the alert immediately and act on it as necessary if they happen to be online.

In this support article, we walk you through the steps required to successfully integrate LogicMonitor's alerting system with the on-premises version of HipChat:

  1. Obtain API information from HipChat
  2. Set HipChat properties in LogicMonitor
  3. Configure a Custom HTTP delivery method within LogicMonitor
  4. Add the Custom HTTP delivery method to an alert Escalation Chain

Obtain API Information from HipChat

As discussed next, you'll need to obtain both a HipChat API Auth token and the "API ID" for the HipChat room.

Obtain a HipChat API Auth Token

Log in to HipChat from your web browser. From Edit Profile | API access, create a new token of type "Send Notification". In the following screenshot, we have created a token with the label "LogicMonitor".

1a. Obtain a HipChat API Auth Token

Obtain the "API ID" for the HipChat Room

The "API ID" identifies the room in HipChat you want to send alerts to and is accessed from the Rooms tab, as shown next.

1b. Get the "API ID" for the HipChat Room

Set HipChat Properties in LogicMonitor

The Auth Token and room "API ID" will be be used by a LogicMonitor Custom HTTP Delivery Method to route the alerts into HipChat. While you could hardcode them directly into the WebHook, it is best practice to set them as properties within LogicMonitor, just as you would set other authentication credentials such as an SNMP community or a MySQL password.

The properties required for HipChat integration are:

  • hipchat_api.pass
  • hipchat_room_id

These properties correspond to the Auth Token and room "API ID" respectively, gathered earlier from HipChat. They can be set from the global, device group, or device level, depending upon your needs. Properties will apply at the most specific level possible, meaning a group level property will override a global level property. By virtue of this, alerts can be delivered to different HipChat rooms by setting the hipchat_room_id property at the group level, allowing for alerts triggered from within different groups to go to different rooms.

For more information on setting properties, see Device Properties.

Configure a Custom HTTP Delivery Method within LogicMonitor

Custom HTTP alert delivery methods (i.e. Webhooks) allow you to send alert notification data to an external system via HTTP GET or POST requests. As discussed in detail in Custom HTTP Delivery, custom HTTP delivery method are added rom Settings | Integrations.

The custom HTTP configuration settings shown (and discussed) next should be used when working with HipChat's API v.2.

Use different URLs or data formats to notify on various alert activity

Select this option if you would like to customize your alert message based on alert status.

Use the same URL and data to notify on various alert activity

Select this option if you would like to use the same message regardless of alert status.

HTTP Method

Select "HTTP Post."

URL

Your URL should use the following format (replace "hipchat_url", "##hipchat_room_id##" and "##hipchat_api.pass##" with your own information):

https:///v2/room/##hipchat_room_id##/notification?auth_token=##hipchat_api.pass##auth_token=##hipchat_api.pass##

Note: Your HipChat system needs to be accessible externally from the LogicMonitor servers.

Alert Data

Select the Raw option and enter the following into the text box:

{
    "from":  "LogicMonitor",
    "message_format": "text",
    "message": "##ALERTDETAILURL## ##LEVEL## ##HOST## ##DATASOURCE##-##DATAPOINT##: ##VALUE## ##THRESHOLD## (##ALERTSTATUS##)"
}

Format

Select "JSON."

Include an ID provided in HTTP response when updating alert status

Do not select this option. It is specifically for custom HTTP integrations that interact with ticketing solutions.

Add the Custom HTTP Delivery Method to an Alert Escalation Chain

Once configured, the Custom HTTP alert delivery method is now available as an alert destination for any user. For the purpose of HipChat, you will simply want to add one user with this new alert destination to any escalation chain in which you want a message to a HipChat room to be part of the chain. In the example screenshot below, we chose the user Bill. The only difference in using different users is if a reference is made to the ##ADMIN## token in the alert data. If that token is present, then the user for which the alert is being generated will be substituted. In this case we are not referencing ##ADMIN##, so any active user will work.

3. Add the HTTP Delivery Method to an Escalation Chain

Any alert that hits the "HipchatErrors" escalation chain will now send an alert message to the specified HipChat room ("TechOps" in our example):