Integrator > Integration Builder >   Example: Configure an outbound integration

Example: Configure an outbound integration

When the Integration Builder was first introduced at the xMatters User Conference in Las Vegas, it showcased a mash-up integration that used outbound integrations to make updates in either ZenDesk, Slack, or xMatters when responses were submitted to a notification. This is possible because outbound integrations make web requests when actions take place in xMatters, allowing us to connect multiple automated processes together.

In our inbound integration example, we built an integration that created a notification event in xMatters when a web request was received from New Relic. In this example, we'll build an outbound integration that starts a new conference bridge in xMatters.

1. Add a new outbound integration

To begin, we navigate into the Integration Builder on our communication plan, and add a new outbound integration.

2. Include properties in outbound integrations

In this next step, we'll select the event properties that we want to send to the outbound integration.

3. Check the request details in the Activity Stream

We can use the Activity Stream in xMatters to see the input for our integration service. Once we see the content of the webhook, we can transform the content to make sure it does what we want.

By default, the Integration Builder will log the first 25 requests for a new integration. After this, logging is turned off and the Integration Builder will only log requests that throw and error or are canceled. For more information about logging, see Enable logging.

4. Transform the content of the webhook

In this step, we'll create a script that will transform the webhook content into an outbound web request that will trigger a communication plan form to start a conference bridge.

Our conference bridge form needs to be in the same communication plan, and we can add two properties to it that we will populate using the transformation script:

When deployed as a web service, this form can be initiated using a cURL command similar to the following:

curl -1 -H "Content-Type: application/json" --user USERNAME -X POST -d '
  "properties": {
    "details": "",
    "Triage Comment": ""
  "recipients": [
       "targetName": "Operations"
' ""

We need to replicate this cURL command in the transformation script using the built-in HTTP client and endpoints.

5. Check that it works

The final thing to do is to respond to a notification with "P1 Bridge" and make sure everything is working.

This example described how to use an outbound integration to make a request to the xMatters REST API, but the workflow is similar no matters what you want to do. The key steps are:

  • Direct web requests from a form to an outbound integration.
  • Use the transformation script to get the values of event properties from the webhook.
  • Define an endpoint with the base URL and authentication credentials to use with your HTTP request.
  • Use the HTTP client to define the path of the web service you want to call, relative to the base URL of the endpoint you are using.
  • Construct the body of the HTTP request according to the requirements of the API you are using.
  • Submit the HTTP request.

That's it, we're done!

Over to you now: we can't wait to see what you build.