Inbound integrations

You can build an inbound integration to transform incoming web requests from an external application to take action in xMatters.

Why use inbound integrations?

Inbound integrations are primarily used to create an event in xMatters using a communication plan. The transformation script for an inbound integration can receive an incoming HTTP request, parse and modify its data, enrich the data using additional web requests, and finally create an event to send notifications.

Where can you run inbound integrations?

Inbound integrations can be hosted in the xMatters cloud, or run in your own xMatters Agent or Integration Agent.

What actions can inbound integrations perform?

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

  • Create a new xMatters event: Use the incoming request to create a new event using one of the forms in the communication plan.
  • Transform content to create a new xMatters event: Use JavaScript to transform the data of the incoming request to create a new event using one of the forms in the communication plan.
  • Run a script: Execute a script, such as a SOAP or REST request, in xMatters On-Demand or on an xMatters Agent.
How is an inbound integration triggered?

To trigger an inbound integration, use a tool or programming language that supports RESTful requests to make a POST request to the integration URL. For more information about available authentication methods and how to trigger inbound integrations, see Inbound integration service authentication.

When xMatters receives the request, it returns a result that indicates that the request has been accepted for processing. The request also returns the requestId attribute, which can be used to search the Events report for any xMatters events that were triggered as a result of this request. To view whether the integration was processed successfully, log on to the xMatters user interface and view the Activity Stream for the corresponding integration.

Configure inbound integrations

The following sections describe how to configure inbound integrations that perform different actions in the cloud, or in your xMatters Agent or Integration Agent.

Inbound integration authentication

The Integration Builder includes four different methods for authenticating incoming web requests. URL authentication allows anyone with access to an integration URL to trigger the integration. More secure user-based authentication methods include Basic, API Key, or OAuth authentication.

Allow all methods

The default authentication setting for incoming web requests is "Allow all methods", which permits any of the available authentication methods to trigger the integration. You can also select a specific authentication method that's exclusively used to trigger the integration; it's recommended that you choose the most secure method the calling system supports.

Authenticating Users

For integrations configured to use URL or API Key authentication, you are required to select an authenticating user to trigger the integration. Any requests submitted to xMatters using one of these methods will have the same permissions within xMatters as that user in terms of communication plan access, form sender permissions, user and group visibility, etc.

An authenticating user must be someone that you supervise with a role that contains the REST Web Service User function.

The authentication type is preserved when you copy an integration; for API key authentication, the copied integration will have a different secret value. If you import a communication plan with inbound integrations, the authentication type will automatically default to URL authentication.

Notification Flood Control

xMatters includes a notification flood control setting that you can use to prevent users from being flooded with multiple notifications from an inbound integration when they’ve been notified about an incident and might be already working on resolving the issue from their mobile device. You can use this feature to control the maximum number of notifications that are delivered to specific device types during a defined period, such as: no more than two messages every ten minutes to SMS and mobile app devices.

For more information, see Enable notification flood control for an inbound integration.

Notification flood control is a company-level setting that applies only to individual integrations which have it enabled. The default configuration settings for this feature limit notifications to one message every three hundred seconds (or one message every five minutes) to mobile app, SMS, and voice device types.