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

Authentication is not required for incoming web requests by default, but you can enable it for all inbound integration services on a communication plan. When authentication is turned on, xMatters auto-generates a username and password that are required for basic authentication of all incoming web requests to integrations in that communication plan.