Using webhooks to email notifications when incidents trigger, acknowledge, resolve

Follow

Webhooks are essentially small information packets that are sent out via an HTTP POST whenever an event happens in PagerDuty, allowing you to receive event state change notifications at every step of the incident lifecycle. Our Webhooks API documentation describes the format of webhook data, as well as the information contained in each request.

In PagerDuty, webhooks are implemented at the service level under Extensions. Whenever an incident changes state (triggered, acknowledged, resolved, etc.), we'll send an HTTP POST request to your endpoint with all the details about that change to a URL you specify. Once you receive that request at your listener, you can then use and disseminate that information to your users - for example, through email.

You can set up webhooks on each service's Integrations tab, where you'll find a section at the bottom for webhook configuration. To use webhooks, you must enter a URL where those POST requests will be sent, and a name for your endpoint to help you identify it.

You can use RequestBin to see the information that is being transmitted (i.e. the webhook as you would actually receive it) without using your own server. Under the service where you will create the incident you want to follow, enter your RequestBin address (this is the "listener" as it will be listening for webhooks). Then simply trigger an incident, acknowledge, and resolve it, and check your RequestBin; every state change will be shown there, in JSON format.

Example: Send Incident State Change Notifications via Email Using a PHP Script

For this tutorial, you will need to have access to a web server that supports PHP.  

  1. Save one of the PHP files listed here: https://gist.github.com/eurica/6034108

  2. Modify the email address listed to the address that you'd like to get emails for all incident status changes within your text editor: $emailAddress = "CHANGEME@example.com";

  3. Upload the PHP file to your web server.

  4. Log in to your PagerDuty account.

  5. Go go the Configuration menu and select Services, then click the service that you'd like to get notified on incident updates.

  6. By default, you will be directed to the Incidents tab of the service's individual page. To add a webhook, switch over to the Integrations tab.

  7. On the Settings tab, click Add an extension.

  8. For the Extension Type select Generic Webhook, then enter a name for your webhook, paste the URL to the PHP script that you uploaded, and click Save.

Now when an incident is triggered/acknowledged/resolved/etc., you will get an email notification. You can customize the script to format the data to your liking. By default it will tell you the incident status, subject, and service, along with a link to the incident. The full JSON payload is sent with the message.

Have more questions? Submit a request

Comments