Set up an alerting channel

A channel is where ITVA sends incident notifications. By the end of this page, you will have a working channel and a test message to prove it. A channel sends nothing until an alerting rule uses it in an escalation level. For how conditions, incidents, rules, and channels fit together, see the monitoring and alerting overview.

Before you begin

• You need access to the Settings > Alerting page.
• Have the destination ready: the email addresses, the Teams webhook URL, or the URL of your webhook endpoint.

Create a channel

1. Go to Settings > Alerting.
2. In the Channels card, select New Channel.
3. Enter a Name. Each channel in your organization must have a different name.
4. Optional: enter a Description.
5. Under Kind, select Email, Webhook, or Teams.
6. Fill in the fields for that kind. Channel kinds below describes each field.
7. Select Save.

Channel kinds

Email

Add one email address for each entry in Recipients. You must add at least one. ITVA sends each notification to every recipient.

The subject is Alerting Incident #<INCIDENT_ID> | ITVA. All notifications about one incident use the same thread ID, so email clients that support threads show them together.

Teams

Enter the Microsoft Teams webhook URL in URL. ITVA posts each notification to this URL as an Adaptive Card that contains the incident message.

To create the webhook URL in Teams, see Send alerts to a Microsoft Teams channel.

Webhook

A webhook channel sends each notification to your own HTTP endpoint. It has three fields:

• Method: POST sends the payload as a JSON body. GET sends the payload as query parameters.
• URL: the endpoint that receives the notification.
• Payload: a list of keys and values. Each key becomes a field in the JSON body or a query parameter.

Each payload value is a Jinja template. ITVA fills it in for each notification. Use these variables to add the incident message:

For example, with Method set to POST, a key title with the value {{ message.subject }}, and a key body with the value {{ message.text }}, your endpoint receives this JSON body:

{
  "title": "Alerting Incident #<INCIDENT_ID> | ITVA",
  "body": "<INCIDENT_MESSAGE_TEXT>"
}

When ITVA sends a notification

ITVA sends notifications to a channel only through alerting rules:

• When an incident opens, ITVA notifies the channels in the first level of each rule that matches the incident.
• If the incident is still open when it escalates, ITVA notifies the channels in the next level. An incident that someone acknowledged or resolved does not escalate.
• When someone acknowledges, resolves, or comments on the incident, ITVA notifies the channels in the first level of each matching rule.

Check that it worked

1. In the Channels card, open the channel.
2. Select Test Channel.

ITVA shows "A test message has been sent." The destination receives a message with the subject Automated Test | ITVA and the text "This is an automated test of the ITVA system. No action is required."

Troubleshooting

Test Channel shows an error

ITVA could not deliver the test message, and the error comes from the destination. Check the recipients or the URL, then select Edit Channel to correct them. For a webhook, any HTTP error status (4xx or 5xx) from your endpoint counts as a failure.

Administrators get a channel failure email

If a notification fails, ITVA saves the error on the channel and emails every active administrator in your organization. ITVA sends this email only on the first failure, not on each one. Fix the channel, then select Test Channel. When a notification succeeds again, ITVA clears the error and emails the administrators that the channel recovered.