Skip to content

Ntfy Integration Guide

Overview

Integrating Ntfy with UptimeObserver unlocks powerful, real-time monitoring for your systems. By combining UptimeObserver's robust uptime monitoring with Ntfy's instant push notifications, you can ensure that any downtime is immediately brought to your attention, wherever you are. Ntfy is a free, open-source notification service that you can self-host or use via ntfy.sh.

Note

Ntfy integration is available on all UptimeObserver plans. This guide uses ntfy.sh but you can use your own self-hosted server.

Support

If you need help with this integration please reach out to us using the "Need Help?" button on the bottom right corner or send us an email at support@uptimeobserver.com.

Step-by-Step Guide

In Ntfy:

  1. Go to ntfy or access your own Ntfy server.
  2. Click on Subscribe to topic.
  3. Choose a topic name or let Ntfy generate one for you.
  4. Click on Subscribe to start receiving notifications.

Topic Name Security

Anyone who knows your topic name can subscribe to it and see your notifications. Use a long, random topic name for security, or use a self-hosted Ntfy server with authentication.

In UptimeObserver:

  1. Go to UptimeObserver and log in to your account.
  2. Navigate to the Integrations section from your dashboard.
  3. Select Webhooks from the list of available integration options. Add Webhook
  4. You'll need to create two webhooks:
    1. One for declaring an incident
    2. Another for resolving an incident

1. Incident Webhook Setup

Incident Webhook should be used by the Monitor Down event.

  1. Friendly name: Ntfy Incident WH
  2. URL: the Ntfy server URL (example: https://ntfy.sh)
  3. HTTP Method: POST
  4. Authentication: None. If you need to authenticate you can choose Basic Auth.
  5. HTTP Body Encoding: application/json
  6. HTTP Body: Make sure to update the "topic" field to match the name of your Ntfy topic. 
    {
    "topic": "TOPICNAME",
    "title": "Incident on __MONITOR_FRIENDLY_NAME__",
    "message": "Incident on __MONITOR_FRIENDLY_NAME__. Root Cause: __INCIDENT_ROOT_CAUSE__",
    "priority": 5,
    "icon": "https://uptimeobserver.com/uptimeobserver.png",
    "click": "__INCIDENT_URL__",
    "tags": ["rotating_light"],
    "actions": [
        { "action": "view", "label": "Monitor", "url": "__INCIDENT_URL__" },
        { "action": "view", "label": "Incident", "url": "__MONITOR_URL__" }
    ]
}
  7. Click Save Webhook, then test it using the Test Button 🧪.

2. Resolution Webhook Setup

Resolution Webhook should be used by the Monitor Up event.

  1. Friendly name: Ntfy Resolution WH
  2. URL: the Ntfy server URL (example: https://ntfy.sh)
  3. HTTP Method: POST
  4. Authentication: None. If you need to authenticate you can choose Basic Auth.
  5. HTTP Body Encoding: application/json
  6. HTTP Body: Make sure to update the "topic" field to match the name of your Ntfy topic. 
    {
    "topic": "TOPICNAME",
    "title": "Incident Resolved on __MONITOR_FRIENDLY_NAME__",
    "message": "Incident on __MONITOR_FRIENDLY_NAME__ has been resolved",
    "priority": 3,
    "icon": "https://uptimeobserver.com/uptimeobserver.png",
    "click": "__INCIDENT_URL__",
    "tags": ["white_check_mark"],
    "actions": [
        { "action": "view", "label": "Monitor", "url": "__INCIDENT_URL__" },
        { "action": "view", "label": "Incident", "url": "__MONITOR_URL__" }
    ]
}
  7. Click Save Webhook, then test it using the Test Button 🧪.

Once completed, your Ntfy + UptimeObserver integration is ready to automatically manage incidents in real-time!

Enabling Alerts on Monitors

After configuring your webhooks, you must add them as alerts to your monitors:

  1. Navigate to your monitor in the UptimeObserver dashboard.
  2. Scroll down to the Monitor Alerts section.
  3. Click Add Alert.
  4. Configure the incident alert:
    • Alert Type: Webhook
    • Event: Monitor Down
    • Webhook: Select Ntfy Incident WH
  5. Click Save Changes.
  6. Add another alert for resolution:
    • Alert Type: Webhook
    • Event: Monitor Up
    • Webhook: Select Ntfy Resolution WH
  7. Click Save Changes.

Recommendation

Always configure both "Monitor Down" and "Monitor Up" alerts to receive notifications when issues occur and when they're resolved.

Troubleshooting

If you are having trouble receiving alerts or setting up the integration, check the common solutions below.

1. Test Button Failed or No Notification Received

If the test button fails or you don't receive a notification:

  • Check the topic name: Ensure the "topic" field in your webhook body matches exactly the topic you subscribed to in Ntfy (case-sensitive)
  • Verify the URL: The URL should be the base Ntfy server URL (e.g., https://ntfy.sh), not including the topic name
  • JSON formatting: Ensure the HTTP Body is valid JSON—check for missing commas or brackets
  • Subscribe first: Make sure you're subscribed to the topic in the Ntfy app before testing

2. Not Receiving Notifications on Your Device

If the webhook test succeeds but you don't see notifications:

  • Check Ntfy app: Ensure the Ntfy app is installed and you're subscribed to the correct topic
  • Device notifications: Verify notifications are enabled for the Ntfy app in your device settings
  • Background restrictions: Some devices restrict background app activity—ensure Ntfy can run in the background
  • Check web interface: Visit https://ntfy.sh/YOUR_TOPIC in a browser to verify messages are being received

3. Authentication Errors (Self-Hosted Servers)

If you're using a self-hosted Ntfy server with authentication:

  • Enable Basic Auth: In UptimeObserver, select "Basic Auth" for authentication and enter your Ntfy username and password
  • Check credentials: Verify your username and password are correct
  • Server configuration: Ensure your Ntfy server is configured to accept authenticated requests
  • HTTPS required: Authentication should only be used over HTTPS connections

4. Priority Not Working as Expected

If notification priority isn't behaving correctly:

  • Priority values: Ntfy uses 1-5 for priority (1=min, 3=default, 5=max/urgent)
  • Device settings: High-priority notifications may be affected by Do Not Disturb mode
  • Adjust priority: Modify the "priority" value in your webhook body (5 for incidents, 3 for resolutions is recommended)

5. Notifications Going to Wrong Topic

If notifications appear in an unexpected topic:

  • Check topic in both webhooks: Verify the "topic" field is correct in both the incident and resolution webhooks
  • Case sensitivity: Topic names are case-sensitive
  • Copy-paste issues: Re-enter the topic name manually if you suspect copy-paste added hidden characters

6. Self-Hosted Server Connection Issues

If using a self-hosted Ntfy server:

  • Server reachable: Verify your Ntfy server is accessible from the internet (UptimeObserver needs to reach it)
  • Firewall rules: Ensure your firewall allows incoming connections on the Ntfy port
  • SSL certificate: If using HTTPS, ensure your SSL certificate is valid and not self-signed
  • Check server logs: Review your Ntfy server logs for any error messages

7. How to Reset the Integration

If all else fails, try a fresh start:

  1. Delete both webhooks in UptimeObserver
  2. Unsubscribe and re-subscribe to the topic in Ntfy
  3. Follow the Step-by-Step Guide to set up fresh webhooks

How to Uninstall

In UptimeObserver:

  1. Go to UptimeObserver and log in to your account.
  2. Navigate to the Integrations section from your dashboard.
  3. Select Webhooks from the list of available integration options.
  4. Delete both the incident and resolution webhooks.

In Ntfy:

  1. Open the Ntfy app or web interface.
  2. Find the topic you created for UptimeObserver.
  3. Unsubscribe from the topic (optional—you can keep the topic for other uses).