Guide to pganalyze Webhooks: Features and Best Practices
pganalyze monitors Postgres performance and raises issues through its Alerts & Check-Up feature when a check finds a problem with a server, a database or a query. Webhooks, currently in Early Access, send those issues and their state changes to your own services, so a database problem can open a ticket, page someone or feed an internal dashboard.
Read on for how issues get routed to a webhook, the payload fields, the organisation-wide signing secret, and pganalyze's fairly short retry policy.
What are pganalyze webhooks?
A pganalyze webhook is an HTTPS endpoint registered for the whole organisation, described on pganalyze's webhooks page. Registering it isn't enough to receive anything. An issue only reaches a webhook when an Alert Rule routes that check to an Alert Destination containing the webhook. When several rules route the same issue to one webhook, pganalyze sends one request, not one per rule.
Requests follow Standard Webhooks: a JSON POST with webhook-id, webhook-timestamp and webhook-signature headers, signed with a secret shared by every webhook in the organisation. You can also attach your own request headers, such as an Authorization token, when you add the webhook.
pganalyze webhook features
| Feature | Details |
|---|---|
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | webhook-signature |
| Body | JSON |
| Event routing | Body field type |
| Availability | Early Access |
| Who can configure | Members with organisation-wide modify permission |
| Routing | Alert Destinations and Alert Rules |
| Secret | One per organisation; 7-day overlap on rotation |
| Custom headers | Optional, set per webhook |
| Retries | Up to 7 attempts over about 4 hours |
| Redirects | Not followed |
| Auto-disable | 20 consecutive failures spanning more than 24 hours |
| Timeout, source IPs | Not published |
Events and payloads
Webhooks fire on these state changes, for issues of every severity:
| Event | Triggered When | Common Use Cases |
|---|---|---|
issue.triggered | An issue is created | Open a ticket, page on-call |
issue.escalated | An issue's severity increases | Raise urgency, notify a wider group |
issue.downgraded | An issue's severity decreases | Lower urgency |
issue.acknowledged | An issue is acknowledged | Mark a ticket as being worked on |
issue.reopened | An acknowledged issue is reopened | Reopen a ticket |
issue.resolved | An issue is resolved | Close the ticket, clear the alert |
ping | A webhook is tested | Confirm the endpoint is reachable and verifies signatures |
pganalyze publishes one example body, for issue.escalated, with some values elided. Its top-level and data fields are:
| Field | Meaning |
|---|---|
type | The event type, for example issue.escalated. This is what handlers switch on; no header carries it |
id | The event ID. It is also the webhook-id header and stays the same across retries, so it is the idempotency key |
timestamp | ISO 8601 time of the event (the webhook-timestamp header is the send time in Unix seconds) |
version | Payload version (1 in the documented example); the page doesn't describe it |
organization | id and slug of the pganalyze organisation |
data.endpoint | The webhook that received this request (id, name) |
data.issue | The issue: id, severity, state, checkKind, description, queryText, details, createdAt, updatedAt, url, references |
data.server, data.database | Where the issue was found |
data.alertRules, data.alertDestinations | The rules and destinations that routed it |
data.issue.state holds the issue's current state separately from the event type. The data for ping isn't documented, so don't assume data.issue is present on a test event.
Setting up pganalyze webhooks
If the Webhooks panel is missing, ask pganalyze to enable Early Access for your organisation. Then:
- Open Settings > Integrations and click Add Webhook in the Webhooks panel.
- Enter a name and an HTTPS URL that resolves to a public address. Add any request headers your receiver expects.
- Copy the Signing secret and store it as
PGANALYZE_WEBHOOK_SECRET. - Click Test and Add. pganalyze sends a
pingand only saves the webhook if that request succeeds, so the receiver must already be running and verifying with the secret. - Go to Alerts & Check-Up > Alert Destinations, add the webhook to a destination, then route checks to it on the Alert Rules tab.
Editing the URL or the headers later triggers another test. For local development, start the Hookdeck CLI before clicking Test and Add and use the URL it prints:
npx hookdeck-cli listen 3000 pganalyze --path /webhooks/pganalyze
With Hookdeck. Use the URL of a pganalyze source as the webhook URL and paste the organisation's signing secret into it. Because Hookdeck responds 200 to the ping, Test and Add succeeds even before your service is deployed. The source accepts POST only, and requests with bad signatures are recorded as failed verification and kept from your destination.
Securing pganalyze webhooks
pganalyze sends v1, followed by a base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body} in webhook-signature. Its page doesn't say how the secret becomes the key, so this function follows the Standard Webhooks rule of base64-decoding the part after whsec_. It also accepts any of several space-separated signatures, which matters during a rotation:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
A receiver that mirrors issues into an incident tool and passes the ping test:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
const app = express();
app.post('/webhooks/pganalyze', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.PGANALYZE_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const event = parseJsonObject(req.body);
if (!event) return res.sendStatus(400); // signed, but not a JSON object
if (typeof event.type !== 'string') return res.sendStatus(400);
if (event.type === 'ping') return res.sendStatus(200);
const issue = event.data?.issue;
if (!issue || typeof issue !== 'object') return res.sendStatus(400);
try {
if (event.type === 'issue.triggered' || event.type === 'issue.reopened') {
await incidents.open(event.id, issue.id, issue.severity, issue.description, issue.url);
} else if (event.type === 'issue.escalated' || event.type === 'issue.downgraded') {
await incidents.setSeverity(event.id, issue.id, issue.severity);
} else if (event.type === 'issue.resolved') {
await incidents.close(event.id, issue.id);
}
} catch {
return res.sendStatus(503); // not processed, so don't acknowledge
}
return res.sendStatus(200);
});
incidents is your own integration; pass event.id through so a retried event isn't applied twice.
pganalyze doesn't specify a timestamp tolerance. The Standard Webhooks libraries reject timestamps older than five minutes by default, which is fine for direct traffic. Hookdeck, by contrast, has no timestamp window, and its retries and replays carry pganalyze's original webhook-timestamp. If your service sits behind Hookdeck, use a check without an age limit, like the function above.
Make pganalyze webhooks production-ready. Hookdeck Event Gateway receives database alerts even while your incident tooling is down, and holds them well beyond pganalyze's four hours of retries.
pganalyze webhook limitations and pain points
Four hours of retries
The Problem: An alert raised during a longer outage of your receiver never arrives.
Why It Happens: pganalyze retries timeouts, connection and TLS errors, 5xx, 408, 425 and 429 up to 7 attempts over about 4 hours. Every other response fails immediately, and redirects aren't followed.
Workarounds:
- Return
5xxfor transient failures, never a4xx. - Point the webhook at the final URL rather than one that redirects.
- After an outage, review open issues in the pganalyze dashboard.
How Hookdeck Can Help: Hookdeck accepts the alert at once and keeps retrying delivery to your service on a schedule you set.
One secret for the whole organisation
The Problem: Every service that receives pganalyze webhooks holds the same secret, and one leak exposes all of them.
Why It Happens: The signing secret is shared by all webhooks in the organisation.
Workarounds:
- Use the optional request headers to add a per-webhook token as a second check.
- Rotate with Rotate secret; both secrets sign requests for 7 days, so receivers can be updated one at a time.
How Hookdeck Can Help: Verifying at a single Hookdeck source means only Hookdeck needs the secret. Your services can authenticate Hookdeck with their own destination credentials.
The secret's format isn't documented
The Problem: Verification fails with a secret that looks right.
Why It Happens: The documentation never states the secret's form in text; the Add Webhook form shows it masked as whsec_****. Standard Webhooks tooling, including Hookdeck's source, base64-decodes only a whsec_ value.
Workarounds:
- Reveal the secret and confirm it starts with
whsec_. Paste it whole, prefix included.
How Hookdeck Can Help: A wrong secret shows up as a verification failure on the ping, with the request saved for inspection.
Webhooks disable themselves
The Problem: Alerts stop after a long outage, even after your receiver recovers.
Why It Happens: pganalyze disables a webhook after 20 consecutive failures spread over more than 24 hours.
Workarounds:
- After any extended outage, check the webhook's status in the Webhooks panel and confirm that new issues arrive.
How Hookdeck Can Help: Hookdeck acknowledges every request, so its source never counts as failing however long your own service is down.
Best practices
Test the routing, not just the endpoint
A successful ping proves the URL and secret work, but nothing arrives until an Alert Rule sends checks to a destination containing the webhook. Check both after setup.
Key incidents on data.issue.id
Several events concern one issue over its life. Use data.issue.id to find the incident and id (or webhook-id) to skip duplicates. Our webhook idempotency guide describes the pattern.
Use timestamp, not the header, for ordering
The body's timestamp is when the issue changed; webhook-timestamp is when that attempt was sent. pganalyze doesn't promise ordering, so compare body timestamps or data.issue.updatedAt before applying an older state.
Keep query text out of logs
data.issue.queryText can include SQL from your application. Treat payloads as sensitive and log only IDs and severities.
Conclusion
pganalyze's webhooks connect Postgres issues to the tools your team already uses. Make sure the endpoint passes the ping test, route checks to it through Alert Rules, verify every request against the organisation's whsec_ secret, and plan for retries that stop after about four hours.
Behind Hookdeck Event Gateway, alerts survive longer outages and the secret stays in one place. Start for free and use a pganalyze source for your next webhook.