• To configure a new endpoint from the Integration Builder tab, click Edit Endpoints.
• To configure a new endpoint when building or editing an inbound or outbound integration, in the Transform the content section on the integration's detail page, click Edit Endpoints.

xMatters displays the Endpoints page.

Each communication plan includes a default 'xMatters' endpoint with the base URL set to the hostname of your xMatters instance. This pre-configured endpoint is used to target your xMatters deployment when making web requests to the xMatters REST API from within Integration Builder transformation scripts. You cannot delete or rename the xMatters endpoint in the Integration Builder.

You can configure additional endpoints to use different authentication details, or to target a different URL than that of the default xMatters endpoint.

1. On the Endpoints page, click Add Endpoint and enter the following information:
   1. Name: Type a name that will identify your endpoint within the scripts. (If the name you choose has special characters or spaces, it will need to be escaped within the JavaScript.)
   2. Base URL: Type the base URL, including the http:// or https:// protocol, of the target system. You can append additional paths within the scripts.
   3. Trust self-signed certificates: This optional setting allows you to target HTTPS endpoints secured using self-signed certificates when testing integrations. The base URL of your endpoint must match the common name specified in the certificate. If the certificate is not valid the integration will throw a security exception and fail. Details of the exception will be reported in the Activity Stream.
   4. Authentication: Select an authentication option and provide the required credentials. For more information about authentication options, see Endpoint authentication
2. Click Save Changes.

The trust self-signed certificates setting is returned to a default state of disabled when you export a communication plan.

1. To edit an existing endpoint, click its name in the list on the Endpoints page, and then modify its details.
2. Click Save Changes to apply the new settings to all instances of the endpoint within the communication plan.
3. Click Close to return to the Integration Builder.

To delete an endpoint, click the X beside its name in the list, and then click Delete Endpoint.

For basic authentication, the user's authentication credentials are used only at the time the endpoint is configured. The password value is not stored and does not need to be updated if the user changes their password at a later time.

1. Select Basic from the Authentication drop-down list.
2. Supply a Username and Password credentials for a user with permission to execute API requests, which will be used to create events.

3. Select the Preemptive check box if you'd like to use preemptive HTTP authentication.

You can use the Test Authentication feature to verify your credentials, or run the integration and check the output of the transformation script in the Activity Stream to determine if the OAuth2 endpoint is configured correctly.

1. Select OAuth2 from the Authentication drop-down list.
2. Select a Grant Type.
   • OAuth2 support is currently limited to Password (or resource owner password credentials) authorization flow.
3. Enter the Access Token URL for the application.
4. Provide the credentials required by the OAuth2 server being targeted, which may include: Username, Password, Client ID, or Client Secret.
5. Click Test Authentication to send a test request using your credentials to the target Access Token URL.
   1. If your credentials are correct, the Endpoints page will display a success message. If the request failed, the page will display the error details returned by the target system.
6. Once your credentials have been successfully verified, click Save Changes.

The following example demonstrates how an OAuth2 endpoint would be used to query for a protected resource, and print out the response received:

For force.com integrations, the authentication response contains an "instance_url" parameter that is part of the hostname on which the access token is valid; for example, "https://na34.force.com". This portion of the URL is not known in advance, and is therefore unavailable when configuring your endpoint.

To support these integrations, an OAuth2 (Salesforce) endpoint dynamically changes the URL assigned to the endpoint during execution of the script to match the instance_url property returned in the authentication response.

1. Select OAuth2 (Salesforce) from the Authentication drop-down list.
2. Select a Grant Type.
   • OAuth2 support is currently limited to Password (or resource owner password credentials) authorization flow.
3. Enter the Access Token URL for the application.
4. Provide the credentials required by the OAuth2 server being targeted, which may include: Username, Password, Client ID, or Client Secret.
5. Click Test Authentication to send a test request using your credentials to the target Access Token URL.
   1. If your credentials are correct, the Endpoints page will display a success message. If the request failed, the page will display the error details returned by the target system.
6. Once your credentials have been successfully verified, click Save Changes.

For outbound integrations to Slack, users are not required to enter an access token URL, client ID, or client secret. The Endpoints screen for the Slack authentication method contains a 'Connect' button that initiates the OAuth2 process for Slack which requires users to authorize access to their Slack team. The Slack endpoint requests the following OAuth scopes:

• team:read,
• channels:history
• channels:write
• channels:read
• chat:write:bot

For the full list of available Slack scopes, see https://api.slack.com/docs/oauth-scopes

1. Select Slack from the Authentication drop-down list.
2. Click Connect.
   1. A new browser window will open to slack.com to authorize access to your Slack account.

3. Select or sign into the Slack team that you want to authorize xMatters to access.
4. Click Authorize.

Pop-ups must be enabled in your browser to open the Slack authorization page.

Adding the Slack token to API requests

When calling a Slack endpoint in an HTTP request, you must explicitly add a function call to add the Slack token to your API request, or the endpoint will not authenticate.

To add the authentication token, use the following syntax in the relevant portion of your script:

http.authenticate( '<SlackEndpointName' )

For example:

// Prepare the HTTP request

var slackRequest = http.request({

   'endpoint': 'Slack',

   'method': 'POST',

   'path': 'channels.create?token=' + http.authenticate( 'Slack' ) + '&name=' + channelName

});

var slackResponse = slackRequest.write();

var slackBody     = JSON.parse( slackResponse.body );