PagerDuty webhooks make it easy to build powerful apps and tools that respond to incidents as they happen. Instead of creating scripts that continuously poll PagerDuty APIs, webhooks make it possible for your own services to receive incidents as they are triggered, acknowledged and resolved. For instance, it’s possible to automatically send a postcard to PagerDuty HQ when an incident changes (regular postal charges apply).

A slightly more practical example is something Clay Smith, one of our web engineers, created during our last hackday. He implemented a straightforward webhook consumer that speaks incident messages to the foyer in a lovely Irish lilt:

Getting Started

To enable audible incidents, you’ll need a spare computer, a pair of speakers and some tool that does text-to-speech from the command line. We use the high-quality Irish English voice “Moira” that comes with Mac OS X Mountain Lion. Assuming you’re behind a firewall, you’ll also need some sort of localhost tunneling enabled so PagerDuty can hit your internal webhook endpoint. We recommend using ngrok for this, but it’s also possible to use the python or ruby localtunnel packages.

Creating Your First Webhook with a Localhost Tunnel

First, we’ll install and start ngrok on port 7388 to create a tunnel to localhost that PagerDuty can send incidents to:

$ sh ./ngrok 7388
Tunnel Status                 online
Version                       0.14/0.17
Protocol                      http
Forwarding                    http://2812f1d7.ngrok.com -> 127.0.0.1:7388
Web Interface                 http://localhost:4040
# Conn                        0
Avg Conn Time                 0.00ms

The forwarding URL is what we’ll be using when we create a PagerDuty webhook for a service.

In the PagerDuty web interface, choose a service that you’d like to receive audible alerts. Edit the service, and create a new webhook called “Audible Alert” with the endpoint url: http://<random ngrok key>.ngrok.com/pd-webhook. Don’t forget to add the pd-webhook path if you’re going to be using the tootles node.js script that this blog post uses.

Save the webhook, and then we’re ready to configure the audio output.

Using Tootles, a Node.js Server That Prints Incidents to the Command Line

For our hackday, we created one of the simplest webhook consumers imaginable, called tootles. All tootles does is print each PagerDuty incident received from a webhook to standard out. Leveraging the power of UNIX, we can pipe that output to something more interesting.

After installing tootles, you can start it from the command line:

$ node index.js -o summary

To test, try triggering a manual incident on your service that’s configured with a webhook. You should then see a summary of that incident appear in the output:

$ node index.js -o summary
PagerDuty Alert on Test Service has been triggered: Test 1234

Printing a summary of the incident status changes isn’t very interesting, however. We want Mac OS X to speak the incident in a nice Irish English voice. We can do this by piping the output of tootles to the say command, or any other text-to-speech command line tool if you’re on a different system:

$ node index.js -o summary | xargs -L 1 say

If you’re on a Mac, you can install additional voices for more fun, including a nice Irish English voice called Moira. To have Moira speak your incidents, use the -v flag on the say command:

$ node index.js -o summary | xargs -L 1 say -v Moira

The possibilities are endless, including sending incident summaries to your printer:

$ node index.js -o summary | lpr

While text-to-speech requires a physical computer with speakers, it’s also worth checking out webscript.io if you’d like to try a cloud-hosted solution for custom webhook consumers written in lua.

We’re excited about the possibilities of webhook integrations at PagerDuty and we look forward to hearing from you about how you use webhooks. Contact support at pagerduty dot com for more information if you’d like help with your webhook integration.