Integration Builder security enhancements

Exciting new enhancements are coming to the Integration Builder that will improve integration security, and give you finer control over how interactions between your outbound integrations and xMatters are authenticated.

Among the changes required to implement these features is an update that may affect some of your existing outbound integrations - though we're making sure that anyone who might be affected is contacted ahead of the feature deployment, and that their integrations will continue to run as expected throughout the change.

For anyone interested in the details - and for anyone interested in developing integrations in the future - we thought we'd explain how these changes will affect integrations so that you can spot potential problems if they happen, or just avoid them in the first place.

The xMatters endpoint

The original implementation of the Integration Builder workflow required that you configure an xMatters endpoint that specified a user account to use when the integrations for that form needed to authenticate a request with xMatters. You could then target the xMatters endpoint from your outbound integration scripts with API requests to perform actions in xMatters, such as creating a device, retrieving a list of users, or initiating another event.

Improved authentication process

One of the enhancements in the upcoming 5.5.161 release is a change to how integrations authenticate with xMatters:

Events initiated using any method other than an inbound integration will now authenticate outbound integration script requests using the account of the user who initiated the event.

Events initiated via an inbound integration will still use the xMatters endpoint account to authenticate requests.

For example, let's say you inject an event into xMatters via the POST form trigger, and the communication plan you target includes an outbound integration that is configured to initiate a new conference bridge event when a user responds with a specific response choice. When triggered, the outbound integration will attempt to initiate that event using your credentials, and not the credentials set on the xMatters endpoint in the Integration Builder.

A potential issue

If the event initiator doesn't have the same permission levels as the account you expected to authenticate the requests in your outbound integration scripts, then the request won't be able to execute the required tasks. The script will still run and execute any of the requests for which the initiator DOES have the correct permission levels, but you might encounter a 403: Forbidden (unauthorized_access_error) in your integration's Activity Stream:


This issue could affect:

  • events initiated from within the xMatters mobile app, or by using the web user interface (i.e., the Messaging tab)
  • events triggered via the email form initiation feature
  • events injected via the REST POST form trigger 

Any of these events that target xMatters endpoints within their outbound integration scripts will use the permissions of the initiating user.

As mentioned, events that are initiated using an inbound integration are not affected.

The fix and the prevention

The fix for this issue is mostly just making sure that you've thought through the implications of your integrations, and considered any potential differences in permission levels.

As for what you can do right now, here are some specific places you can check to make sure that your integrations won't run into any issues (for more information about how to perform any of these checks, click the link in each step):

  1. Check the Sender Permissions you currently have in place on your forms. You may need to adjust the sender permissions if you are starting xMatters events using your outbound integrations so that the user who started the original event can initiate the forms referenced in the outbound integrations.
  2. Make sure your event initiators have the roles they need to make request in xMatters. Remember: for a user to make a request via the REST API, they must have the same permissions they would need to perform that action in the web user interface.
  3. For any requests made by your outbound integrations that needs to read or update xMatters data, make sure that your initiators have the correct permissions on other roles that those updates might require. For example, calling the GET people endpoint will require the correct role-on-role permissions for the user who initiated the form to be able to Use or View the relevant users.

Best practices

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. 

Following these best practices should prevent you from experiencing any authentication issues with your outbound integration requests.


If you do encounter any problems, or for technical assistance with these changes, contact xMatters Support.


Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk