Webhooks

We are often asked if we can take some kind of action when we detect a website is down, usually to call some external URL. The purpose could be anything really, but perhaps the most useful application is to change the DNS entry for the down website so it points to the IP address of a backup web server. To meet this need we've developed a robust, event-driven, webhook feature that gives users powerful abilities. Any time we log an event for a monitored device (website, router, etc.), we can trigger a call to an external URL or any HTTP-based API. We can even trigger a series of API calls.

Webhooks Features

  • Triggered by any device event: OnDown, OnUp, OnWarning.
  • Calls to any simple external URL or any HTTP-based API with support for all HTTP methods (GET, POST, PUT, etc.).
  • Support for authentication methods such as Basic Authentication, OAuth, NTLM, etc.
  • Support for multipile, sequential API calls.
  • JSON return values are cached and can be referred to in subsequent calls.
  • API responses can be included in the Webhooks section of alert emails.
  • Account default webhooks triggered for any device in the account including new ones.

Change DNS During Downtime

In this example, when the website goes down, we want to call a URL at DNS Park to change the IP address to point to a backup web server. When the website comes back up, we'll make a similar call to change back to the original IP address.

{
"Name": "DNS Park (DOWN)",
"URL": "https://control.dnspark.com/api/dynamic/update.php",
"Params": {
"hostname": "HOSTNAME",
"ip": "NEW-IP-ADDRESS"
},
"Auth": {
"Type": "Basic",
"User": "USESRNAME",
"Pass": "PASSWORD"
}
}

iOS/Android Push Notifications

An OnDown event can easily trigger an iOS/Android push notification using Pushover.

{
"Name": "Pushover",
"URL": "https://api.pushover.net/1/messages.json",
"Method": "POST",
"Params": {
"token": "PUSHOVER-APP-TOKEN",
"user": "PUSHOVER-USER-TOKEN",
"message": "Website down! Average U.S. response time/rate last 24 hrs is <!REGION1TIME!>/<!REGION1RATE!>."
}
}

A More Complicated Example

If you follow us on Twitter (@Alertra), you may notice that we occasionally tweet the uptime stats for popular destinations on the web. When one of our benchmark websites comes back online after some downtime, we trigger an OnUp event webhook that executes three consecutive API calls. Here's how it works.

Step 1: Get the uptime stats.

First, we call the Alertra API to get the device summary which gives us all the stats we want. To make the call we need to supply the API with with the account API_KEY and the DEVICE_ID for the site that just came back online, and these values are provided to us by the event context. (There are a lot of other helpful values available, too.)

{
"Name": "Alertra API",
"URL": "https://api.alertra.com/v1.1/devices/<!DEVICE_ID!>/summary",
"Headers": {
"Alertra-API-KEY": "<!API_KEY!>"
}
}

Step 2: Tell the world.

When the call for the device summary completes, the JSON values returned by the Alertra API are cached and are now available in the event context. In order to tweet the uptime stats, we need to call the Twitter API using OAuth 1.0 authentication. Interacting with their API isn't really for the faint of heart, but it can be done. (Hint: Go to dev.twitter.com to set up an application and create an access token, and then find a package that will do the OAuth for you.)

{
"Name": "Twitter",
"URL": "https://api.twitter.com/1.1/statuses/update.json",
"Method": "POST",
"Params": {
"status": "<!URL!> is up.
90-day uptime is <!UT90DAY_PCT!>
(Outages=<!UT90DAY_OUTAGES!>).
Response time is <!REGION1TIME!>.
alertra.com #uptime"
},
"Auth": {
"Type": "OAuth1",
"ConsumerKey": "TWITTER-CONSUMER-KEY",
"ConsumerSecret": "TWITTER-CONSUMER-SECRET",
"AccessToken": "TWITTER-ACCESS-TOKEN",
"AccessTokenSecret": "TWITTER-ACCESS-TOKEN-SECRET"
}
}

Step 3: Pause monitoring.

Website outages often come in batches. When it rains it pours, it seems, and we don't want to spam Twitter with frequent posts about a website's troubles. So here, we use the Alertra API to put the device in time out for an hour which will keep us from generating any more alerts until the storm passes. Hopefully things will settle down soon.

{
"Name": "Alertra API",
"Method": "PUT",
"URL": "https://api.alertra.com/v1.1/devices/start-maintenance",
"Headers": {
"Alertra-API-KEY": "<!API_KEY!>"
},
"SendAsJSON": True,
"Data": {
"Specifier": "device_id:<!DEVICE_ID!>",
"Duration": "01:00"
}
}

Adding Webhooks To Your Account

We want to gain some experience with how our users make use of this feature before we commit to a public interface for it. There are also plenty of security issues involved with doing this kind of thing. For now, you'll need to contact support to get your webhooks configured. We'll be glad to help you get this set up, just tell us what you need and give us any information that may be required as indicated by the examples we've shown here.