Agent skill

pganalyze Webhooks Skill

Receive and verify pganalyze webhooks, which follow the Standard Webhooks specification. Use when setting up a pganalyze webhook endpoint, getting the whsec_ signing secret, debugging webhook-id / webhook-timestamp / webhook-signature verification, or handling Alerts & Check-Up events like issue.triggered, issue.escalated, issue.resolved and ping.

Install this skill

npx skills add hookdeck/webhook-skills --skill pganalyze-webhooks


pganalyze is Postgres performance monitoring. Its Webhooks feature (Early Access) sends Alerts & Check-Up issue state changes to your own HTTPS endpoints as signed JSON requests. Signatures follow Standard Webhooks, so each delivery carries webhook-id, webhook-timestamp and webhook-signature headers.

When to Use This Skill

  • How do I receive pganalyze webhooks?
  • How do I verify a pganalyze webhook signature (webhook-signature)?
  • Where do I find my pganalyze webhook signing secret (whsec_...)?
  • How do I handle issue.triggered, issue.escalated, issue.resolved or ping events?
  • How do I route pganalyze Alerts & Check-Up issues to my own service?
  • Why is my pganalyze webhook verification failing, or failing only on retries and replays?

Verification (core)

HeaderValue
webhook-idThe event ID; stays the same across retries. Your idempotency key (it equals the body id)
webhook-timestampUnix seconds
webhook-signatureOne or more space-separated v1,<base64> entries

Signed content is {webhook-id}.{webhook-timestamp}.{raw body}, HMAC-SHA256, base64 output. The signing secret starts with whsec_ and the key is the base64-decoded part after the prefix. Compare against every v1, entry; ignore other versions. If webhook-id is absent, read svix-id, svix-timestamp and svix-signature instead. The examples use the standardwebhooks library (npm and PyPI):

const { Webhook } = require('standardwebhooks');

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyPganalyze(rawBody, headers, secret = process.env.PGANALYZE_WEBHOOK_SECRET) {
  const p = headers['webhook-id'] ? 'webhook' : 'svix'; // fall back to the svix-* names
  new Webhook(secret).verify(rawBody, {
    'webhook-id': headers[`${p}-id`],
    'webhook-timestamp': headers[`${p}-timestamp`],
    'webhook-signature': headers[`${p}-signature`],
  }, { jsonParse: false }); // throws on a bad signature or stale timestamp → respond 401
}

The library always enforces a fixed 5-minute timestamp window. Hookdeck retries and replays resend the original webhook-timestamp, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in references/verification.md, which can drop or widen the window. In Express, read the body with express.raw({ type: '*/*' }) so any content type verifies, and parse JSON only after the check.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Type and Payload

Every body has the same envelope. The event name is the top-level type (no header carries it), and the issue details sit under data:

{
  "type": "issue.escalated",
  "id": "6f1c9a8e-2b3d-4e5f-9a1b-2c3d4e5f6a7b",
  "timestamp": "2026-10-14T17:02:11Z",
  "version": 1,
  "organization": { "id": "9a8e6f1c-9a1b-4e5f-2b3d-2c3f6a7bd4e5", "slug": "acme" },
  "data": {
    "endpoint": { "id": "42", "name": "Ops alert router" },
    "issue": { "id": "12345", "severity": "critical", "state": "triggered", "checkKind": "queries/slowness", "description": "Slow queries on prod-db" },
    "server": { "id": "abc123xyz", "name": "prod-db" },
    "database": { "id": "678", "name": "app_production" },
    "alertRules": [{ "id": "7", "name": "Prod alerts" }],
    "alertDestinations": [{ "id": "9", "name": "SRE Team" }]
  }
}

data.issue.state carries the issue's state separately from the event type. If several alert rules route the same issue to one webhook, it receives a single request.

Common Event Types

EventSent when
issue.triggeredAn issue is created
issue.escalatedAn issue's severity increases
issue.downgradedAn issue's severity decreases
issue.acknowledgedAn issue is acknowledged
issue.reopenedAn acknowledged issue is reopened
issue.resolvedAn issue is resolved
pingA webhook is tested ("Test and Add" or Send test)

Events are sent for issues of all severities. The docs list these 7, so ignore types you don't recognise. ping is a test event, not a challenge: any 2xx passes. See references/overview.md.

Delivery Semantics

Return a 2xx to acknowledge. Timeouts, connection and TLS errors, and HTTP 5xx, 408, 425 and 429 responses are retried, up to 7 attempts over about 4 hours; any other response fails immediately, and redirects are not followed. If 20 deliveries in a row fail over more than 24 hours, pganalyze disables the webhook and e-mails organization members with manage permissions. The docs give no timeout value, so respond quickly and process asynchronously. Deduplicate on webhook-id. Return 400 for missing headers and 401 for a bad signature. The URL must be HTTPS and resolve to a public address.

Environment Variables

PGANALYZE_WEBHOOK_SECRET=whsec_xxxxx   # full value; one signing secret is shared by the whole organization; handlers fail closed (500) without it

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 pganalyze --path /webhooks/pganalyze

The Hookdeck URL is HTTPS and public, so it can be added in Settings > Integrations > Webhooks. Test and Add sends a signed ping.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →