Send Alerts

Trigger Alerts by Email and Trigger Alerts by Webhook are new and improved versions of our Send Alerts workflow.

The Send Alerts workflow is a pre-built workflow template designed to help you start notifying users and groups with minimal setup. It lets you create an alert and send notifications by simply sending an email or HTTP request to xMatters.

Here are some ideas for using this workflow:

  • Start your incident management squad learning how to trigger a notification in xMatters.
  • Use it as the jumping off point (a template one might say) for building out your own, fully customized workflow. Change a few labels, update some response choices, modify an endpoint and presto — you have a production-ready workflow that’s customized for you.
  • Poke around inside and pick it apart to get an understanding of how workflows are built and how the pieces fit together.
  • Use it a handy reference when building your own workflow from scratch.

Install the workflow

  1. Click the Send Alerts tile on the Workflows Templates page.
  2. On the Install Workflow dialog box, give the workflow a name (this must be unique in your instance) and add an optional description.
    • You can edit these later, if needed.
  3. Click Install.
    • After the workflow installs, the screen shows next steps as well an installation log. The installation log gives you additional information about the installation, such as if you have languages in your instance that aren't configured for the messages in the workflow.
  4. To get started right away, simply send an email to the address listed under Try it out, changing the portion of the email address before the @ to the user or group you want to notify. For example, to send notifications to RigelServiceTeam, change your username to RigelServiceTeam.

To send notifications using the HTTP trigger, change who can send notifications using the workflow, or customize the workflow settings, click Open Workflow.

The Send Alerts notification

Here's an example of the out-of-the-box notification:

The notification provides the recipient with the following response choices:

  • Acknowledge - Acknowledge the alert and stop notifying other recipients.
  • Close - Stop notifying other recipients and terminate the alert.
  • Escalate - Immediately notify the next recipient in the escalation.

Configure workflow permissions

Whether you're kicking off an alert by email or via HTTP request, you can fine-tune the sender permissions, granting the ability to create an alert and send notifications to particular users or roles. You can also let other users with the Developer role access and edit the workflow.

  1. Click the Forms tab, click the list beside the form name, and select Sender Permissions.

  1. Search for the users or roles you want to be able to create the alert.
    • The users or roles you select impact the users you can select as authenticating users when using the workflow. If you want to clearly associate that user with a particular workflow or third-party system, you can create an integration user for that purpose (for example, a SendAlert user or a MonitoringToolX user) and give it sender permissions.
  2. Click Save Changes.

Using the workflow

How you actually initiate alerts with the Send Alerts workflow varies depending on whether you're triggering the flow by sending an email or sending an HTTP request.

Out of the box, you can send an email from any address to the address given in the "Next Steps" when you install the workflow, changing the portion of the email address before the @ to the target name of the user or group you want to notify. You can also set the email trigger to only accept emails from an address associated with an user in xMatters, if you want lock it down.

You can also customize the email address you send emails to. By default, the portion after the @ is a randomly assigned sequence of letters and numbers — you may want to customize it to reflect the purpose of the email.

  1. On the Flow Designer tab, click the Send Alert Flow.
  2. Double-click the Initiate by Email trigger to open it (or hover over it and click the pencil icon).

  1. Confirm the authentication method, and update if needed. You can configure the email trigger to either:
    • accept emails from any address. The flow and any connected steps are authenticated using the credentials of the authenticating user. This defaults to you, but you might want to change this to an integration user, if you've set one up.
    • only accept emails from an address associated with a device in xMatters. The flow and any connected steps are authenticated using the permissions of the user the from address belongs to.
  2. Click either Test Email to open your email client with the address in the "To" field or Copy Address to copy it to your clipboard.
    • Your user ID is listed as the name. However, when you send the email, you'll replace this with the users, groups, or dynamic teams you want to target as recipients of the alert notification.
  3. In your email client, add the email content, making sure to include the subject and a body. These become the summary and the message content of the xMatters alert.
  4. For the address, replace your user ID with the name of the user, group, or dynamic team you want to target. If you want include more than one targeted recipient, repeat the address, changing the portion before the @ symbol.

  1. Open the Activity panel to monitor the progress of your flow.

Optional setup changes

There are some optional changes you can make to the email trigger:

  • Trigger Label: You can change the label of the step. You might do this if you're using this workflow for a particular purpose or you plan to add more email triggers onto the canvas.
  • Trigger ID: The trigger ID forms a part of the email address. You can change it to help people sending the email easily see what the email relates to (for example, the trigger ID could be "generic-alert" or "monitoringtoolx").
  1. On the Flow Designer tab, click the Send Alert Flow.
  2. Double-click the Initiate by HTTP (Webhook) trigger to open it (or hover over it and click the pencil icon).

  1. Click Copy to copy the trigger URL to your clipboard.

  1. To initiate the flow, send an HTTP POST request to the URL.
  2. Include the following parameters in the request body:
    • summary: Make sure the body of the request includes the summary, message, and recipients. These become the summary, message, and targeted recipients of the alert.
    • message: Enter the details you want to include in the message body. Make sure to escape backslashes and double quotes.
    • recipients: Enter the target names of the xMatters users, groups, or dynamic teams you want to notify of the alert. Separate multiple recipients with a comma.
  3. Open the Activity panel to monitor the progress of your flow.

Once you're satisfied that the flow is working as you expect, you can set the state of the Initiate by HTTP (Webhook) trigger to Deployed. This is optional; the step works as is in the Send Alert flow. However, it lets anyone with use permissions add it to other flows.

Sample JSON request body 

{
 "summary": "Enter the text you want to use as the summary of the alert notification",
 "message": "Enter the details you want to include in the message body of the alert notification. \nYou can add special characters, but make sure to escape backslashes \\ and double quotes \" in the message parameter.",
 "recipients": "teamrigel, mmcbride"
}

Sample URL-encoded string 

Summary=Enter+Summary+Here&Message=Enter+Message+Here%0AEncode+reserved+characters&Recipients=teamrigel%2Cmmcbride

Sample query parameters 

&Summary=Enter+Summary+Here&Message=Enter+Content+Here%0AEncode+reserved+characters&Recipients=teamrigel%2Cmmcbride

Optional setup changes

There are some optional changes you can make to the HTTP trigger:

  • Authentication user: By default, you're set as the authenticating user. This means the trigger and any connected steps are run using your permissions. You might want to change this to an integration user, if you've set one up.
  • Trigger Label: You can change the label of the step. You might do this if you're using this workflow for a particular purpose or you plan to add more HTTP triggers onto the canvas.

Do more

The Send Alerts workflow gets you creating alerts and sending notifications quickly. There's a lot more you can do if you want to. Here are some ideas:

  • Change the message content or layout: The notification sent to users includes a summary and a detailed message (for example, the subject and the body of an email). You can change this by editing the message design.
  • Change the response options: You can add or remove response options, or change what happens when a recipient selects a particular response.
  • When using the HTTP trigger, you can send information back to the calling system when there is alert activity in xMatters: drag an alert activity trigger onto the canvas and connect and configure a Webhook step to target the calling system.
  • Add additional steps to the flow: use Flow Designer to visually build flows that connect your tools and processes simply by dragging and dropping steps onto a canvas.