Integrator > Integration Builder > Inbound integrations

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.

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.
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. If the integration URL has been configured to use authentication, provide the authorization credentials using HTTP Basic 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.

Inbound integration service authentication

The default authentication method for incoming web requests is URL authentication, which allows anyone with access to an integration URL to trigger the integration. More secure user-based authentication methods are available for securing inbound integrations, including Basic, API Key, or OAuth authentication.

When an integration is configured to use URL or API Key authentication, xMatters generates randomized values that are unique to the logged-in user. 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.

The authentication type is preserved when you copy an integration; note that 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.