Webhooks

pgDash supports notification of alerts and change alerts via Webhooks since version 2.4.11. This document describes the technical details required to write your own Webhook to process these notifications.

General Requirements:

• Webhooks must be provided as a http or https URL. For https URLs the certificate must be valid.

• Notifications are delivered as an HTTP POST request with a content type of application/json. The User-Agent header will begin with pgDash-Webhook. The connection will be closed after a successful request.

• The webhook must process the notification within 3 seconds. If it fails to send a response within this time, pgDash will wait for 5 seconds and retry the request. No more than 3 retries will be attempted. Note that retries are attempted only on timeout, not on the response's HTTP status code.

• The webhook must return a status code of 200 if it receives and processes the request.

• pgDash will discard any response body from the webhook. No response body is required.

Request Body for Alerts:

• Webhook URLs set on the "Alerts" page in pgDash will be invoked whenever there is a change in the alert status of any rule that has been set.

• Notifications are sent only when the status changes, that is, the mechanism is "edge-triggered" and not "level-triggered". In the absence of any notifications it must be assumed that the state indicated by the last-sent notification continues to persist.

• When all alerts clear, a notification is sent without any alert items (the alerts array described below is empty). As per the previous rule, another notification will be sent only when this state changes, that is, when an alert rule is triggered.

• The request body is a JSON object with the following properties:

  • version - integer - the version of the JSON object's schema. Currently always 1. Note that backwards-compatible changes, like adding a new property might be done without incrementing this version number.

  • server - string - the name of the server whose alert status has changed.

  • reported - integer - the timestamp of the pgmetrics report which caused the change in the alert status. The timestamp is represented as the number of seconds since epoch (1 Jan 1970).

  • alerts - array of objects - the list of warning or critical alerts, each as an object with properties as below. Note that if the alerts just cleared and the state went back to normal, this array will be empty. For each separate object that triggered a rule, there will be a separate entry in this array (example if the rule is "Table size is greater than 100 MiB" and two tables qualify, there will be two entries in this array that have the same "text" property.)

    • type - string - one of warn or crit indicating a rule type of warning or critical respectively.

    • text - string - a description of the alert rule, example "Number of backends is greater than 40", "Database size is greater than 1 GiB".

    • value - string - the current value which triggered the rule, example "43", "1.4 GiB"

    • objname - string - the name of the object involved in the alert

    • objlink - string - a URL to the object involved in the alert

    • query - string, optional - if this is a query-level alert, the full SQL query text

Here is an example of the request body:

{
  "version": 1,
  "server": "prod-42",
  "reported": 1567428364,
  "alerts": [
    {
      "type": "warn",
      "text": "Number of backends is greater than 40",
      "value": "43",
      "objname": "inventorydb",
      "objlink": "https://app.pgdash.io/server/prod-42/db/inventorydb"
    },
    {
      "type": "warn",
      "text": "Max time taken by query is greater than 3 minutes",
      "value": "4m",
      "objname": "/*\"\"*/ select *, pg_",
      "objlink": "https://app.pgdash.io/server/prod-42/alerts",
      "query": "/*\"\"*/ select *, pg_sleep($) from testtable"
    },
    {
      "type": "crit",
      "text": "Database size is greater than 1 GiB",
      "value": "1.4 GiB",
      "objname": "inventorydb",
      "objlink": "https://app.pgdash.io/server/prod-42/db/inventorydb"
    }
  ]
}

Request Body for Change Alerts:

• Webhook URLs set on the "Change Alerts" page will be invoked whenever changes between consecutive reports (as set by the change alert rules) are detected by pgDash.

• Notifications are sent whenever changes are detected. Each notification is independent, and there is no "state" as for the regular alerts.

• The request body is a JSON object with the following properties:

  • version - integer - the version of the JSON object's schema. Currently always 1. Note that backwards-compatible changes, like adding a new property might be done without incrementing this version number.

  • server - string - the name of the server involved.

  • prevreport - integer - the timestamp (as seconds since epoch 1 Jan 1970) of the previous report which was the basis for the change.

  • currreport - integer - the timestamp (as seconds since epoch 1 Jan 1970) of the current report which has changed since the previous one.

  • changes - array of objects - the list of changes. Each entry is a JSON object with the following properties:

    • item - string - a description of the change

    • prev - string, optional - the previous value, if applicable

    • curr - string, optional - the current value, if applicable

Here is an example of the request body:

{
  "version": 1,
  "server": "prod-42",
  "prevreport": 1567432246,
  "currreport": 1567432291,
  "changes": [
    {
      "item": "New Table Added",
      "curr": "inventorydb.public.dispatch201909"
    },
    {
      "item": "Size of Tablespace \"pg_default\" Changed",
      "prev": "53 GiB",
      "curr": "54 GiB"
    }
  ]
}