Hipchat Integration



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 Platform. The Conference Bridge inbound integration script 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 callbacks from xMatters 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.

Create a REST API user

This integration requires a REST API user to authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to have a dedicated “REST Web Service User” role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or ask your xMatters Client Success Manager to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)

In the following example, this role is named “REST Web Service User”.

To create a REST API user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user.
  4. Assign the user to the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password.
Make a note of these details; you will need them when configuring other parts of this integration.

Create users and groups to target

The integration will notify the group or the 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. 

For more information about creating users, groups, and devices in xMatters, refer to the xMatters On-Demand help.

Import the communication plan

The next step is to import the communication plan and the included integrations.

To import the communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Browse, and then locate the downloaded communication plan.
  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, click Create Event Web Service.
    • After you create the web service, the drop-down list label will change to Web Service Only.
  7. In the Web Service Only drop-down list, click Permissions.
  8. Enter the REST API user you created above, and then click Save Changes.

Accessing integration service URLs

Each integration service has its own URL that you can use to target it from Hipchat.

To get a web service URL for an integration service:

  1. On the Integration Builder tab, expand the list of inbound integrations.
  2. Click the gear icon beside the integration service you want to target, and then select Integration URL.

You’ll need this URL when you configure the rest of the integration.

Configure the integration

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

Create a Hipchat integration

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. Under the Summary section, click the Integrations link, and then click the Build your own integration tile.

Hipchat will display the "Build your own" integration page:

In the Name your integration box, type xMatters and then click Create.

The next page contains the URL that xMatters will need to post messages to this room. Make a note of this URL (or copy it to a text file) for later:


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.

  1. 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.
  2. In the We will POST to this URL box, enter the URL from the Conference Bridge integration in the Integration Builder (as explained in the Accessing integration service URLs section, above). 


Configure the integration in xMatters

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

  1. Log in to xMatters and open the Hipchat communications plan.
  2. Click the Integration Builder tab, and then click the Endpoints button.
  3. In the Endpoints dialog box, select the Hipchat endpoint.
  4. In the Base URL box, enter the URL from the inbound Hipchat URL above, and then click Save.
  5. Click the Forms tab, and then click Edit > Layout.
  6. In the Recipients section, specify the individual users or groups that will be notified by this integration.

Pro xMatters tip! You could also create a subscription form and use it to subscribe users or groups.

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 will be sent along to the recipients when they are invited.) As the event is created and notifications are delivered to devices, the integration will post the information to the room.


Hipchat does not produce logs, so the first (and likely only) stop for all troubleshooting investigation will be 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
  • 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