March 21 Andre

Webhooks

Posted in Features |  Comments

In addition to email and SMS, Scout now sports a flexible new alerting option: webhooks. When a trigger generates an alert, Scout can post the alert details to a URL of your choice.

To Enable Webhooks in Scout

1. click “notifications” at the top
2. enter a URL for the webhook endpoint:

Entering a URL here enables webhook posts for all the servers on your account.

What URL should you use? It’s up to you – you’ll need a small web app running somewhere to receive the webhook and do something interesting with it. There’s a very simple Sinatra example is at the end of this blog post.

So What Gets Posted?

Scout performs an HTTP POST with a single field, payload. The field contains the following JSON structure:

{
  "id": 999999,
  "time": "2012-03-05T15:36:51Z",
  "server_name": "Blade",
  "server_hostname": blade,
  "lifecycle": "start", // can be [start|end]
  "title": "Last minute met or exceeded 3.00 , increasing to 3.50 at 01:06AM",
  "plugin_name": "Load Average",
  "metric_name": "last_minute",
  "metric_value": 3.5,
  "severity": "warning" // warning = normal threshold, critical = SMS threshold
}

Notes:

• An alert generates two webhook calls over its lifetime. The first call will have lifecycle:"start". The second call is like the “back to normal” emails, and will have a lifecycle:"end" field.
• Only triggers generate webhook calls. Errors do not generate webhook calls. Alerts generated explicitly by a plugin (as opposed to being generated by a trigger) also don’t generate webhooks.

What can I do with webhooks?

Whatever you want! DM yourself on twitter. Post to your team’s campfire room. Automate to your heart’s content. Here’s a simple webhook endpoint in Sinatra that writes alerts to an “alerts.txt” file:

require 'rubygems'
require 'sinatra'
require 'json'

post '/log' do
  payload=params[:payload]
  alert = JSON.parse(payload)
  File.open "alerts.txt", "a" do |f|
    f.puts "#{alert['server_name']}: #{alert['title']}" 
  end
end

If you run this on a server someplace and direct Scout’s webhooks to it, you’re up and running with webhooks.

Questions?

As always, we’re listening at support@scoutapp.com if you have any questions!