Pagerduty API service (alert)

This guide will walk through setting up a RESTful API service in pagerduty and call it using Advanced REST client tool.  You could of course use curl, but I prefer the Google Chrome Extension Advanced RESTClient.  If you are unfamiliar with the Advanced REST client tool I did a write up on it at http://www.whiteboardcoder.com/2014/10/chrome-extensions-advanced-rest-client.html

This guide assumes you already have a pagerduty account and understand the basics, like how to create an escalation policy.  If you don’t check out my guide at http://www.whiteboardcoder.com/2014/08/pagerduty-getting-started.html

For more detailed information about pagerduty's APIs check out these links http://developer.pagerduty.com/documentation/integration/events [1]

And very specific info on the json format for triggering events can be found at http://developer.pagerduty.com/documentation/integration/events/trigger [2]

Create the service

Login to pagerduty

Click on Services

Click on "+ Add New Service

Give it a name and select an escalation Policy.

Select "Use our API directly and click on Add Service.

Copy the Service API Key.  

Use the REST API

To trigger the event you need to POST a JSON file to pagerduty's REST API.

The URL to POST to is

https://events.pagerduty.com/generic/2010-04-15/create_event.json

I am going to use the Google Chrome Extension "Advanced Rest Client API" to POST to the given pagerduty URL

Here is the JSON payload I sent. 

{     "service_key": "59XXXXXXXXXXd",     "event_type": "trigger",     "incident_key": "server-01-issue",     "description": "FAILURE for production server open http://www.example.com",     "client":"http://www.example.com",     "client_url": "http://www.example.com",     "details": {         "ping time": ">1500ms",         "load avg": 0.75,         "message": "I'm gonna sing the doom song http://youtu.be/LQKag_OBHqc"     } }

Put your own service API key in this JSON and POST it.

If you are using Advanced Rest Client just click Send.

You should get back this response.

Which means you successfully triggered the event.

CURL

Here is an example using the curl command line tool.  (put in your own API service_key)

>  curl -H "Content-type: application/json" -X POST \     -d '{          "service_key": "59XXXXXXXd",       "event_type": "trigger",       "incident_key": "server-01-issue",       "description": "FAILURE for production server open http://www.example.com",       "client": "http://www.example.com",       "client_url": "http://www.example.com",       "details": {         "ping time": "1500ms",         "load avg": 0.75,         "message": "I\u0027m gonna sing the doom song http://youtu.be/LQKag_OBHqc"       }     }' \     "https://events.pagerduty.com/generic/2010-04-15/create_event.json"

JSON format

Let me go into a little detail on the JSON format.

{     "service_key": "59XXXXXXXXXXd",     "event_type": "trigger",     "incident_key": "server-01-issue",     "description": "FAILURE for production server open http://www.example.com",     "client":"http://www.example.com",     "client_url": "http://www.example.com",     "details": {         "ping time": ">1500ms",         "load avg": 0.75,         "message": "I'm gonna sing the doom song http://youtu.be/LQKag_OBHqc"     } }

client and client_url

After creating an incident, if you look at the Pagerduty dashboard

You will see in the details the linkfrom client_url!  This can be very useful!  I recommend using putting in a good URL that can help you diagnose your systems (maybe a link to your Sensu/Nagios/Splunk Servers)

{     "service_key": "59XXXXXXXXXXd",     "event_type": "trigger",     "incident_key": "server-01-issue",     "description": "FAILURE for production server open http://www.example.com",     "client":"http://www.example.com",     "client_url": "http://www.example.com",     "details": {         "ping time": ">1500ms",         "load avg": 0.75,         "message": "I'm gonna sing the doom song http://youtu.be/LQKag_OBHqc"     } }

Use the details section to put information in the message!

Open the incident and click on View Message

The JSON is within the message and URL links even work from the WebApp and from iOS and I believe the android app.

Looking at the iOS you need to open the message then the links are clickable (even though they don't look like it…. Maybe something that needs to be tweaked in the next Pagerduty app update…)

If your contact info is set up to email you and you happen to use Gmail, your email will look like this when you open it.

It's even smart enough to show the YouTube video I linked to.

That's it for this write up I hope it helps you create your own Pagerduty API services (alerts). 

Future Development

I hope to work with Twilio and Parse Cloud code in the next few weeks to get a Twilio phone number to trigger a Pagerduty API service (alert).  I already did a write up on how to use Twilio and Twimlets to trigger an email Pagerduty service (alert), which you can read here http://www.whiteboardcoder.com/2014/10/setting-up-phone-number-to-activate.html

 I think using Twilio with Parse Cloud Code to trigger a Pagerduty API service will be much cleaner and give you a lot more capabilities, especially on the Twilio side.

References

[1]        Pagerduty Developer Integration API

                        http://developer.pagerduty.com/documentation/integration/events

                Accessed 10/2014

[2]        Pagerduty Developer Trigger Events

                        http://developer.pagerduty.com/documentation/integration/events/trigger

                Accessed 10/2014 

This post is a part of and epic, the pagerduty and twilio epic.

Epic Goal:   Set up a phone number, via twillio, that when called will set off a pagerduty event.