Send incidents to xMatters

You can configure APEX AIOps Incident Management to send incidents to xMatters.

Before you begin

Before you set up your xMatters integration:

Make sure you are signed in to your Incident Management instance.
Make sure you have an Incident Management API key to use with your integration. To create a new API key, read Create an API key.
Make sure you are signed in to xMatters.

Install the workflow in xMatters

Configure xMatters for the integration:

In xMatters, navigate to Workflows > Workflow Templates.
Find the Moogsoft Incidents tile and click Add.
Provide a name for the workflow (this must be unique in your xMatters instance) and add an optional description.
Click Next.
Copy the Trigger URL and save it for later use.
Click Close.
Open the Moogsoft Incidents workflow.
Click the Flow Designer tab.
Open the Moogsoft Incidents canvas.
Expand the Components menu.
Select Constants.
The workflow contains two constants for you: One for the API key, and the other for the custom user property.

Configure the CREATE webhook endpoint in Incident Management

Once you have finished configuring xMatters, you will need to create new incident webhook endpoints in Incident Management in order to pass data from Incident Management to xMatters. This section explains how to set up the xMatters CREATE webhook endpoint, which creates new incidents in xMatters when incidents appear in Incident Management.

To configure the CREATE webhook endpoint:

In Incident Management, navigate to Integrations > Outbound Integrations > Webhook Endpoint > Incident Webhook Endpoint.
Click Add Incident Webhook Endpoint and enter "xMatters CREATE" as the name of the webhook endpoint. Optionally, provide a description.
Complete each section of the webhook endpoint according to the following:
1. Skip the Triggers section.
2. Configure the Endpoint:
  1. Set the Request Method to POST.
  2. Under URL, copy and paste the Trigger URL provided earlier in xMatters.
  3. Optionally, modify the URL by adding the target names of any xMatters recipients you want to notify when the alert fires.
    If you used URL authentication when configuring the Moogsoft Incidents workflow in xMatters, use an ampersand to attach recipients.
    For example, if you want to notify Steve Wiseman and the on-call members in the group responsible for the Hyperion service, you'd add &recipients=swiseman,hyperion to the URL.
    For other authentication types, use a question mark to attach recipients.
    For example, if you want to notify Jenn Gladstone and the on-call members in the group responsible for the Ares service, you'd add ?recipients=jgladstone,ares to the URL.
  4. Under Authorization, make sure No auth is selected.
3. Specify the Payload Body:
  1. Replace the default payload with the following:
    { "timestamp": "$created_at", "location": "$tags.region", "severity": "$severity", "id": "$id", "description": "$description", "services": $services, "status": "$status", "totalalerts": "$total_alerts", "signalMode": "New", "assignee": "$assignee", "correlationDefinition": "$correlation_definition", "incidentURL": "$incident_url" }
  2. Scroll up to the top of the page and click Test in the upper right-hand corner. You should see response details and a confirmation that the webhook endpoint is configured correctly.
  3. Make additional payload adjustments according to your business needs. To learn more about fine-tuning your outbound payload, read Configure the CREATE payload body for a webhook endpoint.
4. Save the webhook endpoint.

Configure the UPDATE webhook endpoint in Incident Management

Next, create an xMatters UPDATE webhook endpoint, which sends updates to xMatters when Incident Management incidents are changed.

To configure the UPDATE webhook endpoint:

Navigate to Integrations > Outbound Integrations > Webhook Endpoint > Incident Webhook Endpoint.
At the far right side of the "xMatters CREATE" webhook endpoint you just configured, click on the copy icon:
Enter "xMatters UPDATE" for the name of the duplicate webhook endpoint and click Duplicate.
Click on the "xMatters UPDATE" webhook endpoint to open it.
Click Edit.
Under the Triggers section, select the conditions that you would like to trigger the webhook endpoint.

Under the Payload Body section, replace the existing payload with the following:

{
    "timestamp": "$created_at",
    "location": "$tags.region",
    "severity": "$severity",
    "id": "$id",
    "description": "$description",
    "services": $services,
    "status": "$status",
    "totalalerts": "$total_alerts",
    "signalMode": "Update",
    "assignee": "$assignee",
    "correlationDefinition": "$correlation_definition",
    "incidentURL": "$incident_url"
}

Save the webhook endpoint.

Configure the CREATE workflow in Incident Management

Configure an incident workflow called xMatters CREATE Workflow, which triggers the "xMatters CREATE" webhook endpoint when an incident is created in Incident Management.

To configure the CREATE workflow:

In Incident Management, navigate to Correlate & Automate > Workflow Engine > Incident Workflows.
Click Add Workflow and enter "xMatters CREATE Workflow" as the name of the workflow. Optionally, provide a description.
For the Trigger, select New incidents only.
If applicable, add a filter condition on the incidents that you wish to forward to xMatters.
Click Add Action, select the Send to Endpoint action and then click Add Selected Action.
Select the new Send to Endpoint action and complete each section according to the following:
1. Webhook: Select the "xMatters CREATE" incident webhook endpoint that you created earlier.
2. External Link: Skip this section.
3. Integration Name: Enter the following (without quotes): "xMatters Integration"
  Skip all remaining sections.
Save and Enable the workflow.

Configure the UPDATE workflow in Incident Management

Finally, configure another incident workflow called xMatters UPDATE Workflow, which triggers the "xMatters UPDATE" webhook endpoint to send data when an incident is updated in Incident Management.

To configure the UPDATE workflow:

Navigate to Correlate & Automate > Workflow Engine > Incident Workflows.
Click Add Workflow and enter "xMatters UPDATE Workflow" as the name of the workflow. Optionally, provide a description.
For the Trigger, select Changed incidents only.
Click Add Action, select the Send to Endpoint action and then click Add Selected Action.
Select the new Send to Endpoint action and complete each section as follows:
1. Webhook: Select the "xMatters UPDATE" incident webhook endpoint that you created earlier.
2. External Link: Skip this section.
3. Integration Name: Enter the following: "xMatters Integration"
  Skip all remaining sections.
Save and Enable the workflow.

Test the integration

Within Incident Management, navigate to Integrations > Ingestion Services > Events API.
Add your API key to the provided cURL command and run the command in an external terminal to send an event to Incident Management.
Verify that an incident has been created in Incident Management.
Within xMatters, verify that incident data from Incident Management has arrived.
If you have enabled updates and included Status changed as a trigger, close the incident in Incident Management and verify in xMatters that updated incident data has arrived.

In this section: