Hipchat Integration

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.


This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Hipchat.

NOTE: We have another HipChat integration that uses the HipChat Connect framework which allows a more native feel. Both integrations will work with HipChat cloud or on premise and both will work in conjunction with each other. The Connect integration can be found here.

How it works

Hipchat is a DevOps corporate messaging tool, created by Atlassian. The integration with xMatters provides a way to initiate a conference bridge and invite pre-defined users.

Inbound to xMatters

The /xm_conf is called a slash command and when this is the first string in a message entered by a user into the Hipchat chat window, the xMatters integration is engaged and an HTTP POST is sent from Hipchat to the Integration. The Conference Bridge inbound integration adds the relevant properties from Hipchat to the xMatters event payload. An example Hipchat payload looks like this:

  "event": "room_message",
  "item": {
    "message": {
      "date": "2016-03-04T21:42:36.400164+00:00",
      "from": {
        "id": 333,
        "links": {
          "self": "https://api.hipchat.com/v2/user/111"
        "mention_name": "TravisDePuy",
        "name": "Travis DePuy",
        "version": "89HORBWX"
      "id": "111-222-333-444-555",
      "mentions": [],
      "message": "/xm_conf Everything is broken. And on fire. And it's flooding. And the gophers are eating the LAN cables",
      "type": "message"
    "room": {
      "id": 111,
      "is_archived": false,
      "links": {
        "participants": "https://api.hipchat.com/v2/room/111/participant",
        "self": "https://api.hipchat.com/v2/room/111",
        "webhooks": "https://api.hipchat.com/v2/room/111/webhook"
      "name": "Major Incidents",
      "privacy": "public",
      "version": "04ALIFU5"
  "oauth_client_id": "UUID-HERE",
  "webhook_id": 4131003

The item.message.message is stripped of the /xm_conf and passed as the “main” message sent to the recipients

Outbound to Hipchat

The outbound integrations from xMatters (formerly called callbacks) are captured in one of the three outbound integration scripts and a Hipchat card is crafted to display the relevant information. The POST /v2/room/{room_id_or_name}/notification API is called to post the message to the room.

Download the integration package

To begin, download the communication plan attached to this article; it contains everything needed for this integration. 

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Set up an integration user

This integration requires a user who can authenticate REST web service calls when working with events – these permissions are provided by the "REST Web Service User" role in xMatters.

For Free and Trial customers, your system has an "Integration User" already configured with the REST Web Service User role, so you don't need to burn up an extra user from your limited supply. Make sure you've changed this user's password from the default, then you're good to go.

For everyone else, we recommend you create a user specifically for this integration because this user appears as the initiator or submitter of events from the integration (in messages, the Communication Center, event reports, etc.). Give this user the "REST Web Service User" role and a profile that lets you easily identify the user as specific to the integration – for example:

  • User ID: hipchat
  • First name: Hipchat
  • Last name: Integration

Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration.

Create users and groups to target

The integration notifies the group or user defined as a recipient in the communication plan's Conference Bridge form. If the recipient is not defined, the xMatters event will not be created. 

Import the communication plan

The next step is to import the communication plan into xMatters.

To import the communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Choose File, and then locate the downloaded communication plan (.zip file).
  3. Click Import Plan.
  4. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  5. In the Edit drop-down list, select Forms.
  6. For the "Invite to Conference" form, in the Not Deployed drop-down list, select Enable for Web Service.
    • After you create the web service, the drop-down list changes to Web Service.
  7. Click the Edit drop-down list for the plan, and select Access Permissions.
  8. Add the integration user, and then click Save Changes.
  9. In the Web Service drop-down list, click Sender Permissions.
  10. Add the integration user, and then click Save Changes.
  11. Click the Forms tab, and then click Edit > Layout.
  12. In the Recipients section, specify the individual users or groups that you want to be notified by this integration.

Configure inbound integrations

You need to retrieve the URL of the inbound integration to configure Hipchat. (The following steps assume that you are using the URL Authentication option, which is the default setting for this communication plan. For more information about these options, see Inbound integration service authentication.)

To configure an inbound integration and retrieve its URL:

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the name of the integration to view its details.
  3. Scroll down to How to trigger the integration at the bottom of the page, and select the integration user as the authenticating user (make sure the authentication method is set to URL authentication). The URL trigger is updated to reflect the new user.
    • To be able to select the integration user, you need to be a supervisor of that user and the user needs to be assigned to the REST Web Services role.
  4. Click Copy beside the Trigger field:


Configure Hipchat

Now that you've configured xMatters (at least the parts you can do so far), you can configure the integration in Hipchat.

Create a Hipchat integration

  1. To start configuring Hipchat, log in to the target Hipchat instance and navigate to the room you want to configure: on the Group Admin tab, click Rooms, and then click the name of the target room.
  2. Under the Summary section, click the Integrations link, and then click the Build your own integration tile.
    • Hipchat displays the "Build your own" integration page:


  1. In the Name your integration box, type xMatters and then click Create.
    • The next page contains the URL that xMatters needs to post messages to this room. Make a note of this URL (or copy it to a text file) for later:


  1. At the bottom of the page, in the Extend Hipchat with your commands section, select the Add a command check box to display details on how to kick off an xMatters event.
    • In the Enter your slash command box, enter /xm_conf.
      The integration is pre-configured to expect this value; if you want to use a different value, you must update the code in the integration's transformation script.
    • In the We will POST to this URL box, enter the URL from the Conference Bridge integration in the Integration Builder. 


Configure the Hipchat endpoint in xMatters

Now that you've set up the integration in Hipchat, you can configure the Hipchat endpoint in xMatters:

  1. Log in to xMatters and open the Hipchat communication plan.
  2. Click the Integration Builder tab, and then click Edit Endpoints.
  3. In the Endpoints dialog box, select the Hipchat endpoint.
  4. In the Base URL box, enter the URL from the Hipchat integration you configured above, and then click Save Changes.

Test the integration

In Hipchat, open the room the integration was installed to and type /xm_conf followed by a message. (Everything after the xm_conf is sent along to the recipients when they are invited.) As the event is created and notifications are delivered to devices, the integration posts the information to the room.



Hipchat does not produce logs, so the first (and likely only) stop for all troubleshooting investigation is the Activity Stream in the Integration Builder. The Activity Stream contains all the necessary information about the incoming payload to xMatters as well as any errors that were thrown. (For debugging, make sure to enable logging on the transformation script.)

Download resources


Have more questions? Submit a request


  • 0
    Cameron Stewart

    I just had some back-and-forth with Iain Rose, the product manager responsible for the Integration Builder. His thought is that you haven't associated the callbacks with the outbound integrations.

  • 0
    Travis DePuy

    Hey Kirk,
       Yep, totally doable. The first thing you need to do is enable the "message" property to be available in the outbound integrations. So Navigate to your Hipchat Comm Plan > Forms > Invite to Conference > Layout. Scroll until you see the "message" property and click the gear icon, then check the "Include in Outbound Integrations". This will allow the property to be available in the outbound (callback) scripts. 

    Then, since all the code is housed in the Integration Builder, open up the Integration Builder section. In there, you will find the Outbound integrations, expand those and you should see a link called "Event Status Callback". This fires when an event lifecycle, er, event occurs, such as initialization and termination. 

    Near the bottom there is a variable called "payload" that uses the Hipchat send room notification api. The text you are wanting to change is the "label" value. So change this:

    "label": "Event ID " + callback.eventIdentifier

    To this:

    "label": "Event ID " + callback.eventIdentifier + " - " + callback.eventProperties.message 

    Your text looks slightly different from what I see in the outbound script from the zip file above, so your specific text might be different, but those are generally what you'd need to do. 

    If you want to post your script, we can take a look. 

    Happy Monday!
        --- Travis

  • 0
    Iain Rose

    Hi Chris,

    As Cam mentioned, my suspicion is that the 'callbacks' for your form are not associated with your outbound integrations.

    If you open that menu item, and see that this page is empty then we have found the problem.

    If this is the case, you might be interested to know that removing that extra manual step is one of the major enhancements we're adding to the integration builder in the Task Force X release that's rolling out next week.

    Please let know if this is what's happened here and we can get you up and running asap.


  • 0
    Travis DePuy

    For #1, yea, that would be pretty cool. You could either create a new slash command or you could update the existing script to look for that "DutyRoster" key word and fire the relevant function from there. Either way would work. 
    Once you get the payload into the integration builder, you can use the Group Calendar API call into xMatters to retrieve who's on duty right now. Then you can craft a payload back to Hipchat with the necessary details. 

    For #2, definitely! Especially now that we can have more than one outbound script attached to a Form. As of now, you can't reference outbound integrations from other comm plans, but you can still just copy and paste the script into a new comm plan outbound integration and point the endpoint to the appropriate Hipchat url. 

    For further questions on #1 can we move the discussion over here? I'd be happy to help walk you through the needed code. 

  • 0
    Jordan Olin

    Hi Chris,

    Just a thought, but did you verify the configuration of the endpoint you are using to send the outbound REST request to?  You mentioned the service user, but is the actual URI correct to?

  • 0
    Iain Rose

    Hi Chris,

    The integration should do that already, are you seeing something else?



  • 0
    Kirk Friedman

    Hi Travis and team,

    Is there a way to echo the hipchat message coming from the inbound integration back to hipchat via the outbound integration?  Or more generally to push inbound message information to an outbound integration?

    If the hipchat room is being used by multiple people (AppXSupport room) then anyone who submits an issue will want to that issue synced to an event ID.

    HipChat room: /xm_conf Network connection X is down

    ...delivery and status pinned to event ID 2001234

    HipChat room: /xm_conf Server Y is down

    ...delivery and status pinned to event ID 2001235

    many other hipchat messages in the room for other items


    Status: event ID 2001234: terminated

    (user has to look back through the room to see what this event ID referred to)

    Instead it would be great to see

    Status: event ID 2001234 - Network Connection X is down - Terminated




  • 0
    Kirk Friedman
  • 0
    Chris Crocco

    Yep, the URI for the room is the same for both the inbound and outbound integrations. We have the transform setup to report responses in the activity stream, but there is nothing in the activity stream at all for outbound. The inbound is going through without issue and the callback in the inbound script to the hipchat room is working.

  • 0
    Kirk Friedman

    HI Travis,

    Of course there's more.  After demoing some hipchat integration stuff some users were wondering:
    1) It would be great if we could find out who's on call 

    2) Can we have other responses, not just those originating on hipchat show up on hipchat?  For example someone initiates a report via filling out a scenario

    So for 1) is there a way to pull in group information via the Inbound Integration so someone could say 

    /xm_conf DutyRoster (or some equivalent)

    and get that list?  I see the REST API entries but not sure they work for within an Inbound integration


    Edited by Kirk Friedman
  • 0
    Doug Peete

    I ran into that while developing the integration... I was using the "Duplicate Event" selection under the "Options" dropdown. Unfortunately that generates the event with the old context for whatever the original triggering of the event was. And if that was before your Outbound Integration existed it will not run. We are looking at changing that.

    Net-net: are you duplicating the original event from before the integration existed, or are you using new ones?

  • 0
    Doug Peete

    Chris - another longshot here, but if you go into the Properties report for the event do you see your Outbound integration listed:

  • 0
    Kirk Friedman

    Hi Travis,

    Works great!  Thanks

  • 0
    Chris Crocco


    We have our hipchat integration working for inbound items, but when trying to get an outbound integration to post responses to the same room working, we are not seeing anything in the activity stream.

    We've confirmed the room is correct and it is using the same REST services user as the inbound integration, any thoughts?

  • 0
    Chris Crocco

    No, only seeing the input:

  • 0
    Chris Crocco

    That was it! I knew I was forgetting something....

    Next question is, can we get the comments from an event (i.e. the response comment someone sends from the App) included in the callbacks so it is sent back to hipchat?

Please sign in to leave a comment.
Powered by Zendesk