Datadog

To install this integration in xMatters, simply go to Workflow Templates on the Workflows tab and start typing the name of the integration you're looking for to filter the list. Once you find it, click its tile then click Next to get to the configuration screen.

1. Log into Datadog.
2. Click Integrations > APIs.
• You can find your API Key in the Key column of the API Keys list.
3. To create a new Application Key for xMatters, type a name for the key (for example, "xMatters") in the New application key field, and click Create Application Key.
4. You can now copy the application key from the Hash column in the Application Keys list.

(Datadog Reference)

1. Log in as an administrator, and then click Integrations > Integrations. 
2. Locate and click the Webhooks badge.
3. On the Configuration tab, click New to create a new webhook.
4. In the Name field, type xmatters_alert, then paste the URL for that webhook in the URL field.
5. Paste the payload from the integration configuration page in xMatters into the Payload field.
6. Click Save.
7. Repeat steps 3-6 for the remaining webhooks: xmatters_on_call, xmatters_engage, and xmatters_conference.

5. Click Save.

Your integration is now complete!

1. Click Monitors > Manage Monitors.
2. Click the monitor with alerts you want to send to xMatters, and then click the Edit tab.
3. In the Say what's happening section, type the message you want to send, and include the following to initiate the webhook:

@webhook-xmatters_alert

Notes

• Monitor bodies allow you to send different information depending on the transition of the monitor; for example, when transitioning to alert state or recovery state.
• If you do not want to receive alerts when the monitor moves to a "No_Data" state, you may need to wrap the webhook @-mention in is_alert tags; i.e., {{#is_alert}} {{/is_alert}}
• If you want the integration to automatically terminate xMatters events for recovered alerts, you will need to also wrap a webhook @-mention in {{#is_recovery}} {{/is_recovery}}
• For more details on message template variables, consult the Datadog documentation.

The Engage with xMatters feature allows users to provide updates, request help, or start a conference bridge with colleagues from other teams to collaborate on events, event stream posts or snapshots within Datadog. You can try out the Engage with xMatters feature using the Event Stream or a Snapshot Comment.

To engage with xMatters:

1. Click Events.
2. In the Leave a status update field for an event, use the following format to initiate the webhook (see the Notes below for more syntax information):

<message_text> @webhook-xmatters_engage <recipient>

3. Click Post to create the post in Datadog and trigger the event in xMatters.
•  If enabled, outbound integrations for status updates, delivery notifications and response updates will create comments and other updates on the Datadog post.

Notes

Engage with xMatters posts have some important required formatting:

• All text preceding the @-mention is used as the message when sending notifications to the recipients.
• All text after the @-mention must identify the recipients. For example, in the screenshot above, the "Database" and "Hardware" xMatters groups are targeted for notification.
• You can use the same format to initiate the xmatters_conference webhook. 
• If you want to specify an external conference bridge for an xmatters_conference webhook, add -bridge <bridge_name>, where <bridge_name> is a valid conference bridge already configured in xMatters. For example:

Please join the conference @webhook-xmatters_conference Database Hardware -bridge "My External Conference"

The Who's On Call feature displays current xMatters shift information within the Datadog event stream - no need to open a new browser window or login to xMatters.

For example, a DevOps team member wants to place a direct call to someone on the database team to confirm a solution. Instead of looking up the team in a company directory or calling a data center and hoping someone picks up, the DevOps person can use the Who's On Call webhook to see who is the right primary on-call person in the database group to contact.

When using the Who's On Call feature, you can use two different post types.

To test the Who's On Call feature:

1. Click Events.
2. In the Leave a status update field for an event, use the following format to initiate the webhook (see the Notes below for more syntax information):

@webhook-xmatters_on_call <group>

3. Click Post.
• xMatters displays the Who's On Call results.

Notes

• Any text after the @-mention determines the type of Who's On Call you want to make.
• To get a group listing, leave the text after the @-mention empty or add -page x where x is a positive integer. The xMatters integration will reply with the page of groups for the value of x or, if empty, the first page of groups:

• To get on call shift details for a specific group, enter the name of a valid xMatters group after the @-mention. The xMattersintegration will reply with all active shifts for that group and the team members who are on call:

First, in Datadog, any errors in connecting to the URL encountered by the webhook create new events in the Datadog Event Stream. For example:

The failing webhook is highlighted in the payload, indicating that you are not authorized to access the @webhook-xmatters_engage feature.

The first place to look is the Activity Stream for the integration (click the gear icon and select Open Activity Stream). If there is an entry here, the request reached xMatters. Inspect the details for any errors. 

For the two-way integration from xMatters to Datadog, the activity stream is the primary source of logging.

For example, if you are troubleshooting why a ticket was not assigned to a user after they replied with "Assign to me", check the Activity Steam for the notification responses:

After you convert the integration to a custom workflow, you can configure it to use Basic authentication instead of URL authentication. If you switch the authentication from URL to Basic, you need to update the xMatters webhooks in Datadog to include an authorization header with the base64-encoded username and password of the integration user you created above.

You can create this value by following the instructions below:

• Go to https://www.base64encode.org/.
• In the “Encode to Base64 format” area, type the username and password of the integration user, separated by a colon (for example, datadog:5x>W!AkdfaHJd6092D)
• Click Encode, and copy the result.

Example: dXNlcm5hbWU6cGFzc3dvcmQ=

Update each xMatters webhook in Datadog by adding the following text to the Headers field, replacing <authentication_header_value> with the encoded result from above.

{
"Authorization": "Basic <authentication_header_value>"
}

Example: