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
  • date: the date and time the webhook is created
  • event properties: values of form properties flagged to be included in the webhook

In addition to this common information, each type of webhook payload includes information about the action that triggered it.

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.