Join GitHub today
xmatters Alerting Channel #75
Alert Notifications with xMatters
To integrate xMatters with Scout's Alert Notification system, you can utilize the Webhook feature on the Application > Notification Channels page.
In order for Scout and xMatters to be able to work together, you need to use a third-party service called Zapier.
Zapier is a service which allows you to connect different web services together to make custom work-flows.
First of all you will need to create an account with Zapier, and once you have done this, you can go ahead and create a Zap, by clicking on the Make a Zap! button on the top right-hand side of the screen, as shown in the image below.
You need to create a Trigger (for Scout) and an Action (for xMatters) in order to make the two systems able to communicate. First of all, create the trigger by selecting Webhooks by Zapier as the App you want to work with.
Next you will need to select the type of trigger that you want, select Catch Hook. Next you will be given a URL, which is the Webhook that we will use to link to in Scout. Copy this URL and then open up Scout.
In Scout, navigate to Application > Notification Channels and create a new Webhook, like the picture below, copying in the Zapier URL.
Next you will need to add or edit a Notification Group to include this new channel.
Create an Alert
At this point if you try to carry on creating the Zap in Zapier, it will try to pull a sample Alert from Scout using the Webhook that we set up. The reason it does this is that it requires sample data from Scout in order to understand the format of the trigger, and what fields are available from the Scout. However, at this point there are not going to be any Alerts it can use because this Webhook has only just been set up. So here you have two options:
We strongly recommend the first option, because later on when you are specifying the message that you are going to send to xMatters, if you do not have sample data, you will not be able to use data that came from Scout.
Open up Scout, go to Alert > Alert Conditions and create a simple condition that will alert, and choose the xMatters Notification Group we set up earlier.
Choose the Alert in Zapier
After the Alert has occurred in Scout, go back to Zapier and click the Ok, I did this button and it will connect with Scout and look for an Alert with this matching Webhook. Choose this as the sample you want to use and click Continue.
Create a xMatters Action
Next you need to add an Action step to the work-flow, this is the part were we integrate xMatters. Click Add a Step on the left-hand side of the page.
Next click the Action/Search option, and you will be given the option to choose an app to connect.
Choose xMatters, and then a new Action will be created on the left-hand side of the screen.
Connect to xMatters
After you select the xMatters App, you will be asked to connect to your xMatters account within Zapier. In order to do this, you will have to open xMatters and do some configuration. But before you do that, click the Connect an Account button and a pop-up window will appear, do not fill in your details yet but keep the window open as we need it in a moment after we have configured xMatters.
Once you have opened xMatters and logged in, go to USERS on the top menu, and then click on the Integration User, this is the account that we are going to use to connect Zapier with xMatters.
On the Integration User screen click on the Change Login button so that you can give this user a password. Also make sure that you make a note of the Web Login field for this user.
Next we will need to give this user permission to be able to send a message. To do this click on ROLES and add the Full Access User Role and then click Save. This will grant access to the Send Messages function which is required.
Now go back to the pop-up window from earlier, and type the Web Login (which just noted down) into the Username box and type in the password we set up and your xMatters host name. After you click the Yes, Continue button, your xMatters account can be used in Zapier.
Now is a good time to test if this worked before moving on.
Before carrying on in Zapier, there is one more thing we need to do in xMatters. Click on the DEVELOPER link on the main screen and then click the green Edit button of the Communication Plan that you want to use, and then click Forms.
On the Send Alert form, click the drop down box and choose Access Web Service URL, and copy the URL that appears on the screen. We are going to use this in Zapier next.
Finish configuring Zapier
Going back to Zapier, we need to select the type of Action that will occur in xMatters when our Scout Alert triggers. There is only one to choose, Create Event, so go with that one and click continue.
The next step is to configure the details of this Create Event. First of all, paste the URL that you got from xMatters into the Web Service URL field. Next, for the Properties field, choose which information from Scout that you want to appear in xMatters. The box on the left corresponds to the fields in xMatters that you want to populate, and the box on the right corresponds to the fields coming from Scout. It is only possible to pull this data from Scout here if you created an Alert earlier like we advised.
Then it would be a good idea to test that the Action works correctly.
Then all that's left to do is to give your Zap a descriptive name and enable it.
Now everything is set up so that whenever an Alert occurs in Scout which is linked to this Notification Channel, you will see a message in xMatters.