Outbound integrations

Outbound integrations enable web applications and integrations to extract information from an xMatters event and take action based on the properties of the event. You can configure the webhook used in an outbound integration for event status changes, event comments, device deliveries, notification responses, and escalations. A webhook's payload contains information about the action that triggered it and may include the value of some form properties.

Why use outbound integrations?

The applications of outbound integrations are endless; the following examples are just some of the various ways you can use them:

Notify a help desk system that a user has responded to a notification with a comment or has commented on the event. The help desk system could add the comment to the associated ticket or assign the ticket to the user who made the response.

Maintain your own log of xMatters events for auditing purposes. You can archive these logs indefinitely to achieve compliance to industry standards for accountability.

Maintain a two-way email integration between xMatters and a third-party application.

Outbound integrations can be configured for use with any web application able to consume POST requests over HTTP, or with integrations that use the xMatters Integration Agent in indirect mode.

Where can you run outbound integrations?

Outbound integrations can be hosted in the xMatters cloud, or run in your own xMatters Agent. The outbound integration can also trigger behaviors on the Integration Agent.

What actions can outbound integrations perform?

You can configure an outbound integration to perform one of the following actions:

Run a script: Execute a script, such as a SOAP or REST request, in xMatters.

Send a webhook: Send a web request to an HTTP endpoint.

Send to Integration Agent: Send webhooks to an Integration Agent or integration service.

How is an outbound integration triggered?

When creating an outbound integration, you select the type of system activity that you want to trigger the integration: event status updates, device delivery updates, notification responses, event comments, or escalations.

You can create multiple outbound integrations for the same communication plan form and type of system activity. For more information about how outbound integrations create and send webhooks, see Outbound integration triggers.

These triggers can be especially powerful when used in conjunction with the xMatters REST API. For more information about using outbound integration triggers with the REST API, see Introduction to xMatters REST APIs.

Are there any best practices for building outbound integrations?

In general, when building integrations, you should:

Make sure that anyone allowed to initiate events also has the correct permissions required for any requests that target xMatters endpoints in the outbound integration scripts.

Modify your outbound integration scripts to handle the cases where the initiating user might not have the required permissions. This is especially important if, for example, you're retrieving a list of users and the returned results will be different if the initiating user doesn't have permission to view some of the people in your system.

This applies to all of your users that are authorized to initiate events for a communication plan with outbound integrations, no matter which method they are using to initiate events.

Outbound integration triggers

Whenever an outbound integration is triggered, it generates a webhook that includes information about the action that triggered the integration, the associated event, and the value of some form properties.

By setting a form property to be included in outbound integrations, you can relay any information that is available to the form when the event is initiated. You can even create form properties that are used exclusively for communicating to third-party systems. For example, you could create a form property that prompts the user to select a category that exists in the third-party system. This value is passed to the webhook but doesn't need to be included in the message body of notifications that are sent to recipients.

Every webhook includes some common information:

event identifier: a unique identifier that can be used to track the event that triggered the integration

Included information: The group containing the shift with the escalation, the reason for the escalation, the user that escalated the event (if applicable), the type of escalation, the recipients the event escalated from, and the recipients the event escalated to. See what's included in the payload.

Examples of when to use this trigger:

Automatically launch a new event warning a manager when an event has escalated to the point where an SLA (service level agreement) is in jeopardy.

Automatically update a chat room warning team members when an event is escalated.

Included information: The user and device that made the response, their response choice, and annotations from the mobile app included with the response. See what's included in the payload.

Examples of when to use this trigger:

Automatically assign an incident when a recipient responds with Accept (or Assign to me or whatever response you have configure for this).

Approve or reject change requests based on responses.

The introduction of event comment webhooks in the Knight quarterly release of xMatters On-Demand allows us to begin deprecating the inclusion of mobile app annotations in response webhooks. We will continue to support the current functionality of response webhooks, including mobile app annotations, for two additional quarterly release cycles.

Trigger: None of the targeted recipients could be immediately notified for an event.

Included information: The type of failure, the first 100 targeted recipients, and the total number of targeted recipients. See what's included in the payload.

Examples of when to use this trigger:

Automatically notify a chat room that an event isn’t currently routing to on-call resources.

For more detailed information about the specific JSON payload for each webhook, refer to the Integration Builder scripting reference.

Configure outbound integrations

The following instructions describe how to configure an outbound integration to perform different actions in the cloud, or in your xMatters Agent or Integration Agent. For more information on sending outbound webhooks to the integration agent, see Outbound integrations to the Integration Agent.

The Event Comments trigger in the instructions below won't (yet) be triggered by comments added using the POST /event/{eventId}/annotations endpoint in the xMatters REST API.

Select the form to use to trigger the integration when the selected system activity occurs for that form.

You can select from any of the forms in the communication plan. Forms do not have to be enabled to configure an integration, but must be enabled before you can use them to send a webhook.

Choose the action that the integration will perform when it is triggered, and the location where it will run:

From the Action drop-down list, select Send a Webhook.

From the Location drop-down list, select xMatters Agents or Cloud.

For integrations running on xMatters Agents, select one or more agent from the list of available agents.

You must be a registered user of an xMatters Agent to select the xMatters Agent option from the location drop-down list. The list of agents only includes xMatters Agents for which you are a registered user.

From the Endpoint drop-down list, select the endpoint that xMatters will send data to when the specified system activity occurs.

Click Edit Endpoint to edit the details of an existing endpoint or to add a new endpoint. You can also optionally append a path to the endpoint's base URL.

In the Name field, type a name for your integration.

This name will be displayed in the list of outbound integrations on the Integration Builder tab, so call your integration something descriptive to be able to identify it later.

Select the form to use to trigger the integration when the selected system activity occurs for that form.

You can select from any of the forms in the communication plan. Forms do not have to be enabled to configure an integration, but must be enabled before you can use them to send a webhook.

Choose the action that the integration will perform when it is triggered, and the location where it will run:

From the Action drop-down list, select Run a script.

From the Location drop-down list, select xMatters Agents or Cloud.

For integrations running on xMatters Agents, select one or more agent from the list of available agents.

You must be a registered user of an xMatters Agent to select the xMatters Agent option from the location drop-down list. The list of agents only includes xMatters Agents for which you are a registered user.

In the Name field, type a name for your integration.

This name will be displayed in the list of outbound integrations on the Integration Builder tab, so call your integration something descriptive to be able to identify it later.

xMatters automatically creates a default transformation script that prepares an HTTP request body using the event properties of the webhook of the selected integration trigger-type. It also includes some commented-out examples of how to prepare an HTTP request to target an endpoint.

Click Create Outbound Integration.

If you chose to modify the transformation script in the previous step, your integration will already have been saved and added. Click Update Outbound Integration to save any additional changes, or click the name of your communication plan in the link at the top of the page to return to the Integration Services screen.

If you change the trigger-type of a saved integration, xMatters does not update the content of the integration's transformation script.

Select the form to use to trigger the integration when the selected system activity occurs for that form.

You can select from any of the forms in the communication plan. Forms do not have to be enabled to configure an integration, but must be enabled before you can use them to send to the Integration Agent.

Choose the action that the integration will perform when it is triggered, and the location where it will run:

From the Action drop-down list, select Send to Integration Agent.

From the Integration Service drop-down list, select the integration service that xMatters will send data to when the integration is triggered. To target a specific Integration Agent, you can enter its Integration Agent ID.