xMatters Hubot Script - ChatOps for the Enterprise!


Hubot is the friendly chat bot built by the people over at Github. Hubot "logs in" as a user to any of the major chat tools. Some notable ones:

  • Slack
  • Gtalk
  • Yammer

Once installed and configured, Hubot can then listen for "send event" and will create an xMatters event and notify the recipients with a message. Callbacks are enabled to allow the bot to post real time event status, device delivery status, and user response information directly to the chat room or direct message. 

How it works

Here is a screen shot of Hubot in action. In this case, Hubot's name is "xbot". The user, "tdepuy", notices something is amiss with the web app and another user, "squirrel", chimes in as having a problem as well. To alert the support group, tdepuy enters the following message into the chat:

send event "P1 Support" The web application is throwing "Error cannot connect" errors

xbot is listening for the "send event" keywords and fires an event targeting the "P1 Support" group. 

As xMatters performs the notifications, the callbacks to Hubot (xbot) are fired and he reports on the progress of the event. "tdepuy" and "unix.admin.guy" are notified via their current devices, but then the 5-minute escalation hits and "max.manager" is notified via mobile phone and responds with "Ack". 

Note: This requires a running instance of Hubot. Check out the Hubot deployment information for the relevant OS to get yours up and running. 

Configure xMatters

To begin, create and configure the necessary components in your xMatters instance.

Create a REST web services user

The first step in configuring xMatters is to create 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 Customer Support 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 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 the Splunk side of the integration.

Create users and groups to receive notifications

The hubot commands can target either users or groups, and xMatters is smart enough to figure out which is which. 

You can also create multiple groups and users at once using the EPIC feature. 

Install the communication plan

  1. Download the communication plan attached at the bottom of this article and save it to a location on your computer.
  2. In the target xMatters system, on the Developer tab, click Import Plan.
  3. Click Browse, and then locate communications plan zip file downloaded in step 1.
  4. Click Import Plan.
  5. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  6. In the Edit drop-down list, select Forms.
  7. For the Message 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.
  • In the Web Service Only drop-down list, click Permissions.
  • Enter the REST API user you created above, and then click Save Changes.
  • Accessing web service URLs

    To get the web service URL for a form, in the Web Service Only drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.

    You'll need these URLs when you configure the rest of the integration. 

    Install the hubot-xmatters script

    The script for interacting with hubot resides on npm here. To install into your hubot project repo, run:

    npm install hubot-xmatters --save

    Then add hubot-xmatters to your external-scripts.json:


    The script has several parameters that need to be set to make it work correctly. 

    EXPRESS_PORT - The port hubot will listen on for callbacks from xMatters
    EXPRESS_USER - Username for basic authentication from xMatters
    EXPRESS_PASSWORD - Password for basic authentication from xMatters
    EXPRESS_ADDRESS - Hostname and protocol for xMatters to make callbacks

    XMATTERS_REST_USERNAME - Username of the user to authenticate to xMatters
    XMATTERS_REST_PASSWORD - Password of the user to authenticate to xMatters
    XMATTERS_URL - The xMatters web service URL endpoint for sending events (retrieved from the form, as explained above).

    Per hubot standard startup, these are generally set as environment variables when the bot is started. For example:

    EXPRESS_PORT=8080 EXPRESS_USER="xMatters" EXPRESS_PASSWORD="xMatters" EXPRESS_ADDRESS="http://myhubothost.company.com" XMATTERS_REST_USERNAME="xBot" XMATTERS_REST_PASSWORD="xBot" XMATTERS_URL="https://instance.dc.xmatters.com/reapi/2015-04-01/forms/UUID-HERE/triggers" HUBOT_SLACK_TOKEN=slack-token-here ./bin/hubot --adapter slack


    If you are into tinkering, you can fork the project on Github. Just send a fork request to the project here



    Was this article helpful?
    0 out of 0 found this helpful



    Please sign in to leave a comment.