Send alerts by email and webhook

A notification channel is an email address or a webhook URL that alert rules send their notifications to. Channels belong to a project, and every rule of the project can use them.

Before you beginCopy Anchor Link

• To add, test, rotate, or delete channels, you need the Owner or Contributor role on the project or its subscription, or a custom role with Manage access to Observability. With Read access, as with the Reader role, you can view the channels, and webhook URLs are shortened to their scheme and host.
• In the console, select the project whose alerts you want to send. The channels page shows the channels of that project.

Open the channels pageCopy Anchor Link

The page, Notification channels, lists each channel with its destination and its status.

Add an email channelCopy Anchor Link

Verify an email addressCopy Anchor Link

An address that belongs to an active user of your organization is verified when you add it. Any other address receives a confirmation email, and the channel receives no alerts until the recipient confirms it.

The channel's status shows where it stands:

To send a new link, open the channel's Row actions menu (⋯), and select Resend confirmation. A new link replaces the previous one.

Notifications for an unconfirmed address are skipped, not held back: the address doesn't receive them after it's confirmed.

Add a webhook channelCopy Anchor Link

A webhook channel is verified when you add it. Its URL must meet these rules:

• It uses https://, and it has at most 2,048 characters.
• It doesn't contain a user name or password.
• Its host resolves only to public IP addresses. Private, loopback, link-local, and other non-public ranges are refused. The platform checks the host at every send, and refuses a non-public IP address written in the URL when you add the channel.

The platform doesn't follow redirects.

Verify webhook requestsCopy Anchor Link

The platform sends each notification as an HTTPS POST with a JSON body and these headers:

In the signature header, <timestamp> is the send time in Unix seconds, and <signature> is the hex-encoded HMAC-SHA256 of <timestamp>.<body>, keyed with the channel's signing secret. To verify a request, compute the same HMAC over the raw request body, as received, and compare it with v1. To reject replayed requests, also refuse requests whose timestamp is older than a tolerance that you choose.

import hashlib
import hmac
import time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    fields = dict(item.split("=", 1) for item in header.split(","))
    timestamp = int(fields["t"])
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256
    ).hexdigest()
    fresh = abs(time.time() - timestamp) <= tolerance
    return fresh and hmac.compare_digest(expected, fields["v1"])

secret is the whole signing secret, including its whsec_ prefix. header is the value of X-Publiccloud-Signature, and body is the raw request body.

The body has these fields:

How notifications are deliveredCopy Anchor Link

Respond with a 2xx status code within 10 seconds. The platform gives up on a request after 15 seconds in total.

While a notification waits for a retry, later notifications of the same rule to the same channel wait behind it, so they arrive in order. Emails follow the same retries when the mail relay fails.

Email notifications. By default, the subject is the new state in brackets, [FIRING] or [RESOLVED], followed by the rule name and the instance. A test has [TEST]. These tags aren't translated, so you can filter your inbox on them. The body names the change, the value, the instance, the project, and the time. The email's language is set when the channel is added, from the language preference of the browser that added it, with English as the fallback.

Send a test notificationCopy Anchor Link

The platform sends the test right away, without retries:

• Test notification delivered. The destination accepted it.
• Not sent: the address is not confirmed yet. Confirm the address first.
• For a failure, the message names the reason. See Troubleshooting.

You can send one test per channel every 60 seconds.

Rotate a signing secretCopy Anchor Link

The old secret stops signing at once, so requests fail your receiver's check until it has the new secret. To get the secret of a webhook channel that a budget created, rotate it in the budget's Edit dialog. See Edit or delete a budget.

Delete a channelCopy Anchor Link

Every rule that listed the channel stops notifying it, and the channel's address or URL is erased. You can't restore a deleted channel.

A channel marked Managed by a budget follows a budget's alert recipient, and you can't delete it here. Change the budget instead. See Create budgets and threshold alerts.

ResultCopy Anchor Link

The channel appears in the list. Once its status is Verified, it receives the notifications of every rule that lists it. To add a channel to a rule, see Create alert rules.

LimitsCopy Anchor Link

TroubleshootingCopy Anchor Link

When a test fails, the message names one of these reasons:

RelatedCopy Anchor Link

• Create alert rules
• What is Monitoring & Alerts?
• Create budgets and threshold alerts
• To manage channels through the REST API, see POST/scopes/{scopeId}/observability/notification-channels.