Quickstart

pingdan monitors HTTP endpoints on a fixed schedule, evaluates a set of assertions against each response, and alerts you when something fails. Here's the whole flow:

1. Create an account and open your dashboard.
2. Add an endpoint: paste a URL and pick the HTTP method.
3. Choose a check interval and what makes a check pass.
4. Attach an alert channel so you hear about failures.

Creating a monitor

A monitor is one URL we call on a schedule. Each monitor has a request (method + URL), a schedule (interval + timeout), and validation rules. Start with the basics:

Method:   GET
URL:      https://api.example.com/healthz
Interval: 1 min
Timeout:  10s
Expected: 200

Check intervals

Choose any interval from 1 minute up to 7 days — pick a number and a unit (minutes, hours or days), or use a quick preset like 5 min, 1 hr or 1 day.

The timeout controls how long we wait for a response before recording a failure.

Assertions

Assertions decide whether a check passes. Each one reads a source, applies a comparison, and checks against a target. Available sources:

• status_code — the HTTP response status
• response_time — latency in milliseconds
• header — a response header by name
• body — the full response body
• json_path — a value resolved from a JSON body

Comparisons include equals, not-equals, greater-than, less-than, contains, not-contains and matches (regex).

JSON path

Use dotted paths to drill into a JSON response. Given this body:

{ "status": "ok", "items": [ { "id": 42 } ] }

The path status resolves to ok, and items.0.id resolves to 42. Combine with any comparison, e.g. assert json_path items.0.id equals 42.

Failure thresholds

To avoid alerting on a single transient blip, a monitor only flips to down after a configurable number of consecutive failed checks. Set it to 1 for instant alerts, or higher to filter noise.

Alert channels

Attach one or more channels to a monitor. When it goes down — and again when it recovers — pingdan notifies each attached channel. SSL-expiry warnings use the same channel set.

• Email — Add an address. The deployment must have RESEND_API_KEY set, and EMAIL_FROM should be a verified sender.
• Telegram — Paste a chat ID. The deployment must have TELEGRAM_BOT_TOKEN set; use getUpdates after messaging the bot to find your chat ID.
• Slack — Create an incoming webhook and paste the hooks.slack.com URL.
• Discord — Create a channel webhook and paste the discord.com/api/webhooks URL.
• Microsoft Teams — Create a Power Automate workflow with a Teams webhook trigger and paste the HTTPS workflow URL.
• Generic webhook — Paste an HTTP(S) URL. Optionally add a signing secret for HMAC verification.
• PagerDuty — Create an Events API v2 integration and paste its routing key.
• ntfy — Enter a topic, optionally a custom server URL and bearer token. The default server is https://ntfy.sh.
• Pushover — Paste a user or group key. The deployment must have PUSHOVER_APP_TOKEN set.
• Twilio SMS — Paste an E.164 phone number such as +15551234567. The deployment must have TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN and TWILIO_FROM set.
• Opsgenie — Paste an API integration key and choose the US or EU region.

Manage channels from the Alerts page. Use Send test after adding credentials so delivery errors surface before an incident. Channels that need deployment credentials only appear in the create form after those environment variables are configured.

Channel setup guides

Each guide ends with the exact value you paste into pingdan. For environment-backed channels, set the deployment variables first, restart the API service, then refresh the Alerts page so the channel type appears.

RESEND_API_KEY=re_xxxxxxxxx
EMAIL_FROM="Pingdan Alerts <[email protected]>"

Email address: [email protected]

TELEGRAM_BOT_TOKEN=123456789:AA...

Telegram chat ID: -1001234567890

Slack webhook URL:
https://hooks.slack.com/services/T00000000/B00000000/xxxxxxxx

Discord webhook URL:
https://discord.com/api/webhooks/1234567890/xxxxxxxx

Power Automate webhook URL:
https://prod-00.westus.logic.azure.com/workflows/.../triggers/manual/paths/invoke?...

Webhook URL: https://example.com/pingdan-alerts
Signing secret: whsec_keep_this_private

Routing key: 0123456789abcdef0123456789abcdef

Topic: production-alerts
Server: https://ntfy.sh
Access token: tk_xxxxxxxxx

PUSHOVER_APP_TOKEN=po_app_xxxxxxxxx

User key: po_user_xxxxxxxxx

TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_FROM=+15550000000

Phone number: +15551234567

API key: 01234567-89ab-cdef-0123-456789abcdef
Region: us

Webhook payload

Generic webhooks receive the full structured alert as JSON. A typical endpoint-down payload looks like this:

{
  "event": "endpoint.down",
  "endpoint": {
    "id": "9d4b2d3c-...",
    "name": "Production API",
    "url": "https://api.example.com/healthz"
  },
  "check": {
    "statusCode": 503,
    "checkedAt": "2026-07-10T08:30:00Z"
  },
  "subject": "[pingdan] Production API — DOWN",
  "body": "Endpoint: Production API\nURL: https://api.example.com/healthz\nState: DOWN\nStatus: 503\nAt: 2026-07-10T08:30:00Z"
}

SSL alerts use event: "ssl.expiring" and include an ssl object with daysLeft and expiresAt. Recovery alerts use event: "endpoint.recovered".

If you set a webhook secret, pingdan signs the exact request body with HMAC-SHA256 and sends X-Pingdan-Signature: sha256=<hex>. In Node.js, verification is:

import crypto from "node:crypto";

const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.PINGDAN_WEBHOOK_SECRET)
  .update(rawRequestBody)
  .digest("hex");

const received = Buffer.from(signature ?? "");
const trusted = Buffer.from(expected);
if (received.length !== trusted.length || !crypto.timingSafeEqual(received, trusted)) {
  throw new Error("bad signature");
}

Webhook recipes

Tools with flexible webhook ingestion can use the generic webhook channel directly:

• Better Stack — create an incoming webhook integration in Better Stack, copy its ingest URL, add a pingdan Generic webhook channel, and attach it to monitors. Use the payload's event and endpoint.id fields for routing or deduplication rules.
• Grafana OnCall — create an HTTP webhook integration, paste the generated URL into a pingdan Generic webhook channel, and map endpoint.down to firing and endpoint.recovered to resolved in the integration template.