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 alert in xMatters using a workflow. 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 alert 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 alert: Use the incoming request to create a new alert using one of the forms in the workflow.
  • Transform content to create a new xMatters alert: Use JavaScript to transform the data of the incoming request to create a new alert using one of the forms in the workflow.
  • Run a script: Execute a script, such as a SOAP or REST request, in xMatters 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 Alerts report for any xMatters alerts 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 panel for the corresponding integration.

The maximum number of requests you can submit within a one-minute period to xMatters is limited by your pricing plan. If you exceed this limit, your request will be rejected with a 429 error and will not be queued for processing.

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 workflow access, form sender permissions, user and group visibility, etc.

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

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 workflow 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.