Notifications

Using notifications, you can alert your team when an endpoint goes down or experiences degraded performance. To add notifications, you have to add environment variables as GitHub repository secrets (Settings -> Secrets -> Actions) and add Environment variable as your Secret name and Value in environment variable as value in secret. DO NOT select Variables select Secret(see Creating and storing encrypted secrets).

Secrets

Every time an endpoint goes down, a notification with the following text is sent:

๐ŸŸฅ Example Site (https://example.koj.co) is down: https://github.com/upptime/upptime/issues/4

If it experiences degraded performance, a notification with the following text is sent:

๐ŸŸจ Example Site (https://example.koj.co) has degraded performance: https://github.com/upptime/upptime/issues/4

When it comes back up, another notification is sent:

๐ŸŸฉ Example Site is back up.

Strategy

If you have more than one configurations of each provider (say multiple email configurations, both SMTP and SES), you can choose the strategy. For each notification provider (Slack, email, etc.), you can specify the strategy using the NOTIFICATION_{PROVIDER}_STRATEGY environment variable, where {PROVIDER} is the constant-case service name, for example NOTIFICATION_SLACK_STRATEGY. The strategy can be any one of:

ValueDescription
fallbackIf one provider returns an error, try the next
roundrobin (default)Use every provider in turns
no-fallbackDeactivates fallback strategy

More information is available on the Multi-provider strategies page in the documentation.

Providers

For each notification type (Slack, email, etc.), you need to first enable it by setting the NOTIFICATION_{PROVIDER} to true, where {PROVIDER} is the constant-case service name, for example NOTIFICATION_SLACK. Each notification type also requires additional environment variables. See the examples below.

Slack

Environment variableValue
NOTIFICATION_SLACKSet to true
NOTIFICATION_SLACK_WEBHOOKSet to true
NOTIFICATION_SLACK_WEBHOOK_URLSlack webhook URL

To create a Slack webhook URL, see the article Incoming webhooks for Slack on the Slack website.

Telegram

Environment variableValue
NOTIFICATION_TELEGRAMSet to true
NOTIFICATION_TELEGRAM_BOT_KEYYour bot key
NOTIFICATION_TELEGRAM_CHAT_IDYour chat ID

To create a Telegram bot key, see the documentation for Botfather on the Telegram Support website.

Discord

Environment variableValue
NOTIFICATION_DISCORDSet to true
NOTIFICATION_DISCORD_WEBHOOKSet to true
NOTIFICATION_DISCORD_WEBHOOK_URLDiscord webhook URL

To create a Discord webhook URL, see the article Intro to Webhooks on the Discord Support website.

Zulip

Environment variableValue
NOTIFICATION_ZULIP_MESSAGE_URLZulip Message API URL
NOTIFICATION_ZULIP_API_EMAILEmail of the Zulip bot
NOTIFICATION_ZULIP_API_KEYAPI Key of the Zulip bot

To create a Zulip Incoming Webhook bot, see the article Add a bot or integration in the Zulip docs. The NOTIFICATION_ZULIP_MESSAGE_URL should include the type, to and topic query params and would look something like this: https://domain.zulipchat.com/api/v1/messages?type=stream&to=general&topic=Upptime%20notifications.

Microsoft Teams

Environment variableValue
NOTIFICATION_TEAMSSet to true
NOTIFICATION_TEAMS_WEBHOOK_URLTeams webhook URL

To create a Microsoft Teams webhook URL, see the article Create Incoming Webhooks on the Microsoft Learn website.

Email

To send an email, you can use SMTP or a hosted service such as AWS SES, Sendgrid, Sparkpost, or Mailgun.

All services require you to specify the email address from and to:

Environment variableValue
NOTIFICATION_EMAILSet to true
NOTIFICATION_EMAIL_FROM"From" email address
NOTIFICATION_EMAIL_TO"To" email address

Sendgrid

Environment variableValue
NOTIFICATION_EMAIL_SENDGRIDSet to true
NOTIFICATION_EMAIL_SENDGRID_API_KEYSendgrid API key

AWS SES

Environment variableValue
NOTIFICATION_EMAIL_SESSet to true
NOTIFICATION_EMAIL_SES_REGIONAWS region
NOTIFICATION_EMAIL_SES_ACCESS_KEY_IDAWS access key ID
NOTIFICATION_EMAIL_SES_SECRET_ACCESS_KEYAWS secret access key
NOTIFICATION_EMAIL_SES_SESSION_TOKENAWS session token

Sparkpost

Environment variableValue
NOTIFICATION_EMAIL_SPARKPOSTSet to true
NOTIFICATION_EMAIL_SPARKPOST_API_KEYSparkpost API key

Mailgun

Environment variableValue
NOTIFICATION_EMAIL_MAILGUNSet to true
NOTIFICATION_EMAIL_MAILGUN_API_KEYMailgun API key
NOTIFICATION_EMAIL_MAILGUN_DOMAIN_NAMEMailgun domain name

SMTP

Environment variableValue
NOTIFICATION_EMAIL_SMTPSet to true
NOTIFICATION_EMAIL_SMTP_PORTSMTP Port
NOTIFICATION_EMAIL_SMTP_HOSTSMTP Host
NOTIFICATION_EMAIL_SMTP_USERNAMESMTP Username
NOTIFICATION_EMAIL_SMTP_PASSWORDSMTP Password

SMS

To send a text message, you can any one of several services: Callr, Clickatell, Infobip, Nexmo, OVH, Plivo, Twilio, or 46elks. You'll have to create an account at the service of your choice and provide authentication information as specified below.

All services require you to specify the phone number from and to:

Environment variableValue
NOTIFICATION_SMS_FROM"From" phone number
NOTIFICATION_SMS_TO"To" phone number

46elks

Environment variableValue
NOTIFICATION_SMS_46ELKSSet to true
NOTIFICATION_SMS_46ELKS_API_USERNAME46elks username
NOTIFICATION_SMS_46ELKS_API_PASSWORD46elks password

Callr

Environment variableValue
NOTIFICATION_SMS_CALLRSet to true
NOTIFICATION_SMS_CALLR_LOGINCallr login
NOTIFICATION_SMS_CALLR_PASSWORDCallr password

Clickatell

Environment variableValue
NOTIFICATION_SMS_CLICKATELLSet to true
NOTIFICATION_SMS_CLICKATELL_API_KEYClickatell API key

Infobip

Environment variableValue
NOTIFICATION_SMS_INFOBIPSet to true
NOTIFICATION_SMS_INFOBIP_USERNAMEInfobip username
NOTIFICATION_SMS_INFOBIP_PASSWORDInfobip password

Nexmo

Environment variableValue
NOTIFICATION_SMS_NEXMOSet to true
NOTIFICATION_SMS_NEXMO_API_KEYNexmo API key
NOTIFICATION_SMS_NEXMO_API_SECRETNexmo API secret

OVH

Environment variableValue
NOTIFICATION_SMS_OVHSet to true
NOTIFICATION_SMS_OVH_APP_KEYOVH app key
NOTIFICATION_SMS_OVH_APP_SECRETOVH app secret
NOTIFICATION_SMS_OVH_CONSUMER_KEYOVH consumer key
NOTIFICATION_SMS_OVH_ACCOUNTOVH account
NOTIFICATION_SMS_OVH_HOSTOVH host

Plivo

Environment variableValue
NOTIFICATION_SMS_PLIVOSet to true
NOTIFICATION_SMS_PLIVO_AUTH_IDPlivo auth ID
NOTIFICATION_SMS_PLIVO_AUTH_TOKENPlivo auth token

Twilio

Environment variableValue
NOTIFICATION_SMS_TWILIOSet to true
NOTIFICATION_SMS_TWILIO_ACCOUNT_SIDTwilio account SID
NOTIFICATION_SMS_TWILIO_AUTH_TOKENTwilio auth token

Custom Notifications

Both the up and down/degraded performance notifications can be customized with your preferred message, configured as an environment variable. Multiple variables are available to use within the message, relating to the site and status.

Environment Variables

ValueDescription
NOTIFICATIONS_DOWN_MESSAGEDown/degraded performance message
NOTIFICATIONS_UP_MESSAGEUp message

Message Variables

ValueExample
$SITE_NAMEExample Site
$SITE_URL(https://example.koj.co)
$ISSUE_URL (down message only)https://github.com/upptime/upptime/issues/4
$RESPONSE_CODE (down message only)500
$STATUS
  • down
  • experiencing degraded performance
  • is back up
  • performance has improved
$EMOJI
  • ๐ŸŸฅ
  • ๐ŸŸจ
  • ๐ŸŸฉ