# pganalyze Webhooks

[pganalyze](https://pganalyze.com) 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)

| 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):

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/pganalyze-webhooks/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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/pganalyze-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/pganalyze-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/pganalyze-webhooks/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`:

```json
{
  "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](https://github.com/hookdeck/webhook-skills/blob/main/skills/pganalyze-webhooks/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

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

```

## Local Development

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/pganalyze-webhooks/references/overview.md) - Event catalog, envelope and payload fields
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pganalyze-webhooks/references/setup.md) - Add a webhook, find and rotate the secret, route issues
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pganalyze-webhooks/references/verification.md) - Library and manual verification, gotchas, debugging