Configuring Custom Postback URL | Webhooks

A webhook, or the Uptime.com Custom Postback URL, allows you to push alerts to any third party system that can expect to receive an application/json encoded payload in the body of a request.

Webhooks are useful for managing alert data internally, and creating a history of specific alerts with the metrics your team needs to know. Unlike specific integrations, which handle data output for visualizing metrics, webhooks require administrators to maintain their own system for translating and receiving this data.

Integration Functionality

  • Receive an HTTP POST in a JSON serialized string containing the expected results
  • Post data received to a third party URL

Integration Setup

The Custom Postback URL first requires you to create your own website or web application. You will need to setup a handler, accessible by a public URL which you enter into the URL field. We will then POST the alert data in JSON format to this URL.

Servers can expect to receive these keys in the HTTP POST in a JSON serialized string:

{
    "data": {
        "account": {
            "brand": "uptime",
            "site_url": "https://uptime.com",
            "id": 76424,
            "name": "NAME"
        },
        "service": {
            "msp_use_ip_version": "",
            "msp_dns_record_type": "",
            "monitoring_service_type": "HTTP",
            "msp_expect_string_type": "STRING",
            "id": 303856,
            "msp_include_in_global_metrics": true,
            "display_name": "Check designed to fail",
            "msp_url_path": "",
            "msp_address": "http://URL.com",
            "msp_protocol": "",
            "msp_threshold": 40,
            "msp_url_scheme": "http",
            "msp_port": null,
            "short_name": "Check designed to fail",
            "msp_expect_string": "",
            "msp_notes": "",
            "monitoring_service_type_display": "HTTP(S)",
            "msp_send_string": "",
            "msp_encryption": "",
            "device_id": 195337,
            "is_paused": false,
            "msp_dns_server": "",
            "msp_username": "",
            "name": "Check designed to fail",
            "msp_sensitivity": 2,
            "msp_interval": 5
        },
        "integration": {
            "is_enabled": true,
            "module_verbose_name": "Custom Postback URL (Webhook)",
            "name": "Hello World",
            "use_legacy_payload": false,
            "id": 1313,
            "module": "webhook",
            "postback_url": "https://engal31sjcwpi.x.pipedream.net/"
        },
        "locations": [
            "US-East",
            "US-West"
        ],
        "device": {
            "is_paused": false,
            "address": "URL.com",
            "display_name": "URL.com",
            "id": 195337,
            "name": ""
        },
        "global_alert_state": {
            "ignored": false,
            "state_has_changed": true,
            "created_at": "2019-04-09T17:18:38.991Z",
            "state_is_up": false,
            "num_locations_down": 2,
            "id": 67726495
        },
        "date": "2019-04-09T17:18:38.991Z",
        "alert": {
            "created_at": "2019-04-09T17:18:38.991Z",
            "state": "CRITICAL",
            "short_output": "Name or service not known\nHTTP CRITICAL - Unable to open TCP socket",
            "is_up": false,
            "output": "Name or service not known\nHTTP CRITICAL - Unable to open TCP socket",
            "id": 67503555
        }
    },
    "event": "alert_raised"
}
 

Basic setup requires a name for your integration, and the URL that will receive the HTTP POST from Uptime.com.

custom-postback-config.png

Once you've configured your Custom Postback URL, you will need to assign it to a contact and make sure that contact is notified when a Check fails.

First, click Notifications>Contacts>New Contact. Select Custom Postback URL from the Push Notifications field within the New Contact screen.

Finally, return to your Check’s Edit screen and assign the Custom Postback URL as one of the Contacts to be notified of a downtime event.

Test your integration with one of the following two options:

  1. Force the Check assigned to your Integration to fail by altering it (HTTPS checks can use a misspelling of the domain, for example)
  2. Click Notifications>Contacts, then click Actions>Test to send a test to the Contact