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.resolvedorpingevents? - 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)
| Header | Value |
|---|---|
webhook-id | The event ID; stays the same across retries. Your idempotency key (it equals the body id) |
webhook-timestamp | Unix seconds |
webhook-signature | One 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
| Event | Sent when |
|---|---|
issue.triggered | An issue is created |
issue.escalated | An issue's severity increases |
issue.downgraded | An issue's severity decreases |
issue.acknowledged | An issue is acknowledged |
issue.reopened | An acknowledged issue is reopened |
issue.resolved | An issue is resolved |
ping | A 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
- references/overview.md - Event catalog, envelope and payload fields
- references/setup.md - Add a webhook, find and rotate the secret, route issues
- references/verification.md - Library and manual verification, gotchas, debugging