API Monitoring with HipChat

HipChat is a chat platform designed for teams. Users create “rooms” where team members can present material and interact. The benefit is that the entire team can easily view the history of the discussion, or search for individual posts, at a single location. Compare this with a team attempting to search old emails to reconstruct a past discussion, and the benefit of HipChat to business teams becomes obvious.

If you are monitoring APIs using the API Science platform, your team can take advantage of HipChat. API monitor alerts can be configured to send messages to a HipChat room any time an API check fails, or returns to service. Since HipChat runs on Mac, Windows, iOS, Android, and Linux, your team can stay connected with what’s happening in your API monitoring no matter where they are, on a 24/7 basis.

To demonstrate this, I created an “API Monitor Alerts” room in the API Science HipChat account:

hipchat-api-monitor-alerts-room

To send messages to the HipChat room, a HipChat contact has to be added to your API Science account. Right-click on your account name at the top right of your dashboard page, and select “Settings”:

lyra-monitors-pulldown

On the Settings page, select “Contact Book”; then click the “New Contact” button:

lyra-contact-book

In the pop-up “Create Contact” dialog, use the pull-down and select “HipChat” as the contact type:

hipchat-contact-type

The “Integration URL” is provided by HipChat. At the top of the HipChat page, click on “Integrations.” Then, use the “Select a room” pull-down to identify the room for which the integration will apply. The integration can be applied to all rooms or a specific room:

hipchat-integration-roomFor this demo, I selected my “API Monitor Alerts” room. HipChat includes preconfigured integration with various apps, but in our case we need to build a custom integration. So, the next step is to click the “Build your own integration” box:

hipchat-build-your-own

HipChat provides two types of “Build your own” integration:

  • Notify People in This Room – enables sending messages from an external application to the HipChat room
  • Extend HipChat with Your Commands – enables sending messages from the HipChat room to an external application

In our case, we want the “API Monitor Alerts” HipChat room to receive messages sent by our API Science monitor.

hipchat-integration-name

At the bottom of this page, enter a name for your integration, then click “Create.”

The next page provides a URL that can be used to post messages to the selected room, along with a curl test that lets you try out your new integration:

hipchat-integration-url

When I click the “Try it!” button, a message is sent to my “API Monitor Alerts” room:

hipchat-integration-test-message

Completing the Integration

Now it’s time to configure your API Science monitor to send messages to the HipChat room. Copy the URL from the HipChat integration page and paste it into the “Integration URL” field in the API Science “Create Contact” dialog, enter a label for the contact, then click the “Create Contact” button:

create-contact-hipchat-url

Return to your API Science dashboard and select the monitor you’d like to connect with your HipChat room. Scroll down to the bottom of the page to the “Alert Rules” section. Add a new alert rule. In the “Select a contact to be alerted” pull-down, select the HipChat contact:

add-hipchat-alert

Then click “Add Rule” to save the new alert. (See my post Configuring API Science API Monitor Notifications for more information on configuring API Science alerts.)

When a monitor check fails, a message is posted in the HipChat room, for example:

hipchat-alert-message

The link brings your team to the API Science detail page for the check that failed.

–Kevin Farnham