Skip to content

Webhooks Integration Guide

Overview

Integrating UptimeObserver with Webhooks enables real-time, automated communication between your uptime monitoring and any external services. Webhooks allow you to send HTTP requests to any URL when monitor events occur, enabling integration with virtually any system that accepts HTTP requests.

Note

Webhooks are available on all plans, subject to advertised webhook allowances.

Prerequisites

Before setting up this integration, you'll need:

  1. An HTTP endpoint that accepts POST requests
  2. The URL of your webhook receiver

Step-by-Step Guide

  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: Declare Incident WH
  2. URL: the webhook URL of your target service
  3. HTTP Method: POST
  4. Authentication: None. If you need to authenticate you can choose Basic Auth or Bearer.
  5. HTTP Body Encoding: application/json
  6. HTTP Body: Customize the body to match your target webhook's expected format. 
    {
    "incident_url": "__INCIDENT_URL__",
    "incident_id": __INCIDENT_ID__,
    "title": "Incident on monitor __MONITOR_ID__",
    "description": "Monitor check failed. Open the incident URL for details.",
    "incident_status": "__INCIDENT_STATUS__",
    "monitor_id": __MONITOR_ID__,
    "monitor_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: Resolve Incident WH
  2. URL: the webhook URL of your target service
  3. HTTP Method: POST
  4. Authentication: None. If you need to authenticate you can choose Basic Auth or Bearer.
  5. HTTP Body Encoding: application/json
  6. HTTP Body: Customize the body to match your target webhook's expected format. 
    {
    "incident_url": "__INCIDENT_URL__",
    "incident_id": __INCIDENT_ID__,
    "title": "Resolved: monitor __MONITOR_ID__",
    "description": "The monitor has recovered.",
    "incident_status": "__INCIDENT_STATUS__",
    "monitor_id": __MONITOR_ID__,
    "monitor_url": "__MONITOR_URL__"
}
  7. Click Save Webhook, then test it using the Test Button 🧪.

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

Body Encoding and Substitution

The HTTP Body field is a text template. UptimeObserver substitutes variables before sending it; the selected encoding sets the Content-Type header.

  • JSON: substitution does not JSON-escape values. A monitor name or root cause containing quotes, backslashes, or newlines can invalidate the payload. The examples above use numeric IDs and generated dashboard URLs instead of free text. If you need arbitrary text, send IDs to an intermediary that obtains the details and constructs the target request safely, rather than inserting free text into this JSON template.
  • Form (application/x-www-form-urlencoded): enter raw key=value&key=value text. After substitution, UptimeObserver splits it at & and URL-encodes each value. Keep literal + in phone numbers; do not enter %2B or pre-encode JSON, because percent signs will be encoded again.
  • Form limitation: & is always treated as a field separator, including inside substituted text or JSON. A literal ampersand in a value cannot be made safe by pre-encoding it. Use IDs, fixed text without ampersands, and generated incident/monitor links, or an intermediary that safely constructs the target request. Form encoding also does not repair invalid JSON in a ContentVariables field.
  • Test button: uses sample IDs, URLs, the name Test Monitor Name, root cause Test root cause, and status Active. It does not simulate a real recovery event and cannot prove that every real value will be safe.

Test both the Monitor Down and Monitor Up templates. For a real end-to-end test, use a dedicated test monitor and recipient; webhook tests can send actual messages and incur third-party charges.

Available Variables

You can use these variables in your webhook body:

  • __MONITOR_FRIENDLY_NAME__ - The name of your monitor
  • __INCIDENT_URL__ - Direct link to the incident details
  • __INCIDENT_ROOT_CAUSE__ - The reason for the incident
  • __INCIDENT_STATUS__ - Current status of the incident
  • __MONITOR_URL__ - Link to the monitor in the dashboard (not the monitored endpoint)
  • __MONITOR_ID__ - Unique monitor identifier
  • __INCIDENT_ID__ - Unique incident identifier

Enabling Alerts on Monitors

Follow Add an alert to a monitor, using Alert Type → Webhook for both rules:

Event Webhook
Monitor Down Declare Incident WH
Monitor Up Resolve Incident WH

Use the test checklist to verify both payloads and actual event delivery.

Troubleshooting

If you are having trouble with webhooks, check the common solutions below.

1. Test Button Failed (Connection Errors)

If the test button fails with a connection error:

  • Check the URL: Verify the webhook URL is correct and accessible from the internet
  • HTTPS issues: If using HTTPS, ensure the SSL certificate is valid and not self-signed
  • Firewall rules: The target server must accept incoming connections from UptimeObserver's IPs (see Bot documentation for IP addresses)
  • Timeout: The webhook endpoint must respond within a reasonable time (typically 30 seconds)

2. HTTP 401 Unauthorized

If you receive a 401 error:

  • Missing authentication: If your endpoint requires authentication, configure Basic Auth or Bearer token in UptimeObserver
  • Wrong credentials: Double-check your username/password for Basic Auth or the token for Bearer authentication
  • Token format: For Bearer authentication, enter only the token value without the "Bearer " prefix

3. HTTP 403 Forbidden

If you receive a 403 error:

  • IP not whitelisted: Your target service may require IP whitelisting. Add UptimeObserver's IPs to your allowlist
  • Authentication scope: Your credentials may not have permission to access the webhook endpoint
  • Rate limiting: Some services block requests that appear automated—contact the target service provider

4. HTTP 404 Not Found

If you receive a 404 error:

  • Wrong URL: Verify the webhook URL is correct, including any path segments
  • Endpoint removed: The webhook endpoint may have been deleted or changed on the target service
  • Trailing slash: Some services require (or reject) a trailing slash in the URL—try both

5. HTTP 500 Internal Server Error

If you receive a 500 error:

  • Invalid JSON: Ensure your HTTP Body is valid JSON with properly quoted keys
  • Unexpected format: The target service may expect a different payload structure—check the service's documentation
  • Server issues: The target service may be experiencing problems—check their status page

6. Webhook Works but Notifications Don't Appear

If webhooks succeed (200 OK) but you don't see the expected result:

  • Payload format: The target service may require specific field names or structures
  • Content-Type header: Ensure HTTP Body Encoding matches what the target expects (usually application/json)
  • Check target service logs: Review logs on your target service to see how the webhook was processed

7. Invalid JSON Errors

If you get JSON parsing errors:

  • Quote all string keys: JSON requires double-quoted keys: "key": "value" not key: "value"
  • Number variables: Variables like __INCIDENT_ID__ are numbers—don't wrap them in quotes
  • String variables: Variables like __MONITOR_URL__ are strings—wrap them in quotes
  • Check for trailing commas: JSON doesn't allow trailing commas after the last item

8. Webhook Triggers But Wrong Data

If the webhook fires but contains wrong information:

  • Check variable names: Ensure variable names are spelled correctly with double underscores on both sides
  • Test with real incident: Some variables only populate during real incidents, not test calls
  • Check event type: Make sure "Monitor Down" triggers your incident webhook, not your resolution webhook

9. How to Reset the Integration

If all else fails, try a fresh start:

  1. Delete the problematic webhooks in UptimeObserver
  2. Create new webhooks with fresh configurations
  3. Test each webhook individually before adding them to monitors

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.

On Your Target Service:

Depending on the service, you may also want to remove any webhook endpoints or integrations you created specifically for UptimeObserver.

Need Help?

If you need help with this integration, please contact us via the support button or email us at support@uptimeobserver.com.