Aldaviva / FreshPager

📟 Trigger a PagerDuty incident when Freshping detects that a service is down.

FreshPager

When Freshping detects an outage, trigger an alert in PagerDuty (and resolve when it's up again).

This is helpful because Freshping's only built-in notification system is email, and the Gmail Android app is extremely slow to notify you of new messages: notifications are often hours late. PagerDuty, on the other hand, has realtime alerting with SMS messages and mobile app push notifications for Android and iOS.

This is a free, open-source, no sign-up, self-hostable alternative to the Zapier Freshping + PagerDuty integration.

1. Prerequisites
2. Installation
3. Configuration
4. Execution
5. Signal Flow

Prerequisites

• .NET Runtime 8 or later
• Freshping account
  • ⛔ Freshworks disabled the ability to sign up for new Freshping accounts in 2023, so if you don't already have an account, you can't create one anymore.
  • All billing plans are compatible: Sprout (free, 5 integrations), Blossom (10 integrations), and Garden (15 integrations)
• Ability to listen on a public WAN TCP port for incoming HTTP requests from Freshping without being blocked by a NAT or firewall
• PagerDuty account (the free plan is sufficient)

Installation

1. Download the ZIP file for your operating system and CPU architecture from the latest release page.
2. Extract the ZIP file to a directory of your choice, such as C:\Program Files\FreshPager\ or /opt/freshpager/.
   • When installing updates, don't overwrite appsettings.json.
3. Install the service so it will start automatically when your computer boots.
   • Windows: & '.\Install service.ps1'
     • If this PowerShell script doesn't run, try removing the Mark of the Web by unblocking the file or calling Set-ExecutionPolicy RemoteSigned.
   • Linux with systemd:

     sudo cp freshpager.service /etc/systemd/system/
     sudo systemctl daemon-reload
     sudo systemctl enable freshpager.service

     • If the installation directory is not /opt/freshpager/, make sure to update freshpager.service to match.

Configuration

1. Create an Integration in PagerDuty and get its Integration Key.
   1. Sign into your PagerDuty account.
   2. Go to Services › Service Directory.
   3. Select an existing Service for which you want to publish events, or create a new Service.
   4. In the Integrations tab of the Service, add a new Integration.
   5. Under Most popular integrations, select Events API V2, then click Add.
   6. Expand the newly-created Integration and copy its Integration Key, which will be used to authorize this program to send Events to the correct Service.
2. Edit the appsettings.json configuration file.

   Key	Example Value	Description
   pagerDutyIntegrationKeysByFreshpingCheck	{ "My Server": "y5mfp…" }	Object where each key is the name of a check in Freshping, and its value is the Integration Key you created for the matching PagerDuty Service in Step 1.
   kestrel.endpoints.https.url	http://0.0.0.0:37374	URI containing the TCP port on which to listen for HTTP requests from the Freshping webhook client. Must be publicly accessible on the WAN.

3. Create Webhook integration in Freshping.
   1. Sign into your Freshworks account.
   2. Go to your Freshping Dashboard.
   3. Go to Settings › Integrations.
   4. Under Webhook, select + Create Integration.
   5. Set the Webook Name to any name you want.
   6. Set the Event Type to Up/Down.
   7. Select the Checks that should trigger the alert.
   8. Set the Callback URL to the location of your FreshPager server, such as http://myserver.example.com:37374/.
   9. Leave the request body set to Simple.
   10. Click Save.

Execution

1. Start the service.
   • Windows: Restart-Service Freshpager
   • Linux with systemd: sudo systemctl restart freshpager.service

Signal Flow

1. Freshping detects and confirms that a Check is down.
2. Freshping sends an HTTP POST request to each Webhook integration subscribed to Up/Down events on that Check.
3. Your FreshPager server receives the HTTP POST request from Freshping.
4. FreshPager looks up the Integration Key in its configuration based on the Check name from the request body.
5. FreshPager sends an Events API V2 request to PagerDuty to trigger an alert on the Service that contains the Integration Key.
6. PagerDuty creates a new incident for this alert, and returns a unique key for this alert, which FreshPager stores in memory.
7. When Freshping detects that the Check is up again, it sends another POST request to FreshPager, which resolves the previously-created PagerDuty alert using the same unique key.