Push notifications via webhook and curl

Prerequisites

• A PagerDeck account with at least one paired device, so alerts have somewhere to land.
• A source in the dashboard with its credentials, see the first step below.
• A system or script that can send HTTPS requests with custom headers.

How to set it up

1. 1

   Create a source

   Create a source in the dashboard. Its ingest key starts with src_live_ and is visible exactly once. Only its SHA-256 is stored.

2. 2

   Send an alert

   dedup_key keeps an incident together: a second request with the same key updates the open message and does not ring again.

   curl -sS -X POST https://api.pagerdeck.com/v1/push \
     -H "Authorization: Bearer $PAGERDECK_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title":"Disk almost full on web-01","body":"/ is 94% used","severity":"error","tags":["prod","disk"],"dedup_key":"web-01:disk"}'

3. 3

   Read the response

   level is the level after your rule chain. deduplicated true means the incident is already open and no second sound played. queued 0 with devices 0 is not an error, the message is then in the history.

   {
     "message_id": "10aa2f31-29f7-4429-94cb-d69cb7bb3227",
     "level": "high",
     "deduplicated": false,
     "queued": 1,
     "devices": 1
   }

4. 4

   Send from Windows

   The same with Invoke-RestMethod. ConvertTo-Json builds the body, and the key comes from an environment variable.

   $headers = @{ Authorization = "Bearer $env:PAGERDECK_KEY" }
   $body = @{
     title     = "Disk almost full on web-01"
     body      = "C: is 94% used"
     severity  = "error"
     tags      = @("prod", "disk")
     dedup_key = "web-01:disk"
   } | ConvertTo-Json
   Invoke-RestMethod -Method Post -Uri "https://api.pagerdeck.com/v1/push" `
     -Headers $headers -ContentType "application/json; charset=utf-8" -Body $body

5. 5

   Resolve

   The same sender closes the incident with the same dedup_key. The all-clear creates no notification and does not count toward any allowance. A second request responds with 404, because the incident is already closed.

   curl -sS -X POST https://api.pagerdeck.com/v1/resolve \
     -H "Authorization: Bearer $PAGERDECK_KEY" \
     -H "Content-Type: application/json" \
     -d '{"dedup_key":"web-01:disk"}'

Payload

PagerDeck reads these fields on POST /v1/push. Only title is required, unknown fields are ignored.

{
  "title": "Disk almost full on web-01",
  "body": "/ is 94% used",
  "severity": "error",
  "tags": [
    "prod",
    "disk"
  ],
  "dedup_key": "web-01:disk",
  "url": "https://status.example.com/web-01",
  "ttl": "30m"
}

title

Required, at most 250 bytes.

body

Body text, at most 8 KiB.

severity

info, warning, error or critical. Without it the source default applies.

tags

At most 20, 64 bytes each.

dedup_key

Keeps an incident together until it is resolved.

url

A link for the app, http and https only.

ttl

Delivery deadline and automatic resolve, for example 30m.

Test it

Send a test alert straight to the API after setting PAGERDECK_KEY to your key. If it shows up in the app under your source, key and source are right and any problem sits in the sender configuration.

curl -sS -X POST https://api.pagerdeck.com/v1/push \
  -H "Authorization: Bearer $PAGERDECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"PagerDeck test","body":"If you read this, the key works.","severity":"warning"}'

What the rules do with it

The sender proposes an urgency, your rule chain decides the alert level. This rule raises errors from the source webhook to critical and repeats until you acknowledge. Use the slug of your own source.

{
  "enabled": true,
  "stop": false,
  "when": {
    "source": [
      "webhook"
    ],
    "severity_at_least": "error"
  },
  "then": {
    "level": "critical",
    "repeat": {
      "every": "5m",
      "until": "ack",
      "max": 6
    }
  }
}

Set the volume

By source, title pattern, tags and time of day you can set a level from silent to critical.

Repeat until acknowledged

A rule repeats an alert at a fixed interval until you acknowledge it.

Escalate

If nobody reacts, PagerDeck notifies another address after a deadline.

What you should know

• The key is never allowed in the query string. It belongs in the header.
• PagerDeck does not check for heartbeats. If you want to detect missing messages, you also need a monitor.
• If you already call Pushover, you can use the Pushover compatible route /1/messages.json instead and only swap the URL, token and user.

Troubleshooting

When the API answers with a status code, it usually names the cause already.

202

Accepted and stored. This is not an error, delivery follows.

400

The input is invalid, for example a title over 250 bytes or malformed JSON. The message field gives the reason.

401

The key is missing, unknown or expired. Check the Authorization: Bearer header and that the key was copied completely.

402

The account may not send. Nothing is wrong with the connection, check the plan and billing in the dashboard.

413

The request is larger than 64 KiB. Limit the amount per request.

429

Sent too fast or quota used up. The Retry-After header says when to continue.

Frequently asked questions

What happens if I send too many requests?

The API responds with 429 rate_limited and Retry-After. Per source, 60 alerts go through immediately, then one per second. Per account, 300 go through immediately, then five per second.

How do I retry after a timeout without a duplicate alert?

Set the Idempotency-Key header. If the body has no dedup_key, PagerDeck uses the header as the dedup_key, and the retry lands on the same message.

What exactly does severity mean?

severity is a suggestion. Without a rule, info becomes low, warning becomes normal, error becomes high and critical becomes critical. Your rule chain can change any mapping.

What happens when the allowance is used up?

From 100 percent, PagerDeck keeps accepting and storing everything, but delivers nothing, not even high and critical, unless you switched on paid additional volume and it covers the alert. From 300 percent, the API responds with 429 quota_exceeded until the next period; alerts delivered as additional volume do not count toward that.

Read next

• Monitor cron jobs and shell scripts with push

  A wrapper script checks the exit code. If something goes wrong, the last output reaches you as an alert.

• Failed GitHub Actions as a push to your phone

  One extra step with if: failure() is enough. The key stays in a secret, and jq builds the payload.

• PagerDeck or Pushover

  Both put a push notification on your phone. The difference is who decides how loud it is.

• Uptime Kuma notifications to your iPhone

  Uptime Kuma reports an outage via webhook. PagerDeck uses your rules to decide whether your phone rings.