Integrator > Integration Builder > Outbound integrations

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, device deliveries, and notification responses. 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. 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.
Where can you run outbound integrations?

Outbound integrations can be hosted in the xMatters cloud, or run in your own xMatters Agent or 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?

You must select the type of system activity that will trigger the integration: event status updates, device delivery updates, or notification responses. 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 webhooks.

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.

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.