Email, webhooks, and scripts

Open Alerts → Notifications and actions…, or Settings → Alerts & notifications → Apply & configure email, webhooks and scripts…. Each action is disabled until explicitly configured and enabled. Press Save actions to persist changes.

Delivery controlsCopy Anchor Link

Actions run serially through a bounded queue. A full queue can reject an event. Failures are logged as action events; they do not stop monitoring. Turning off an action prevents queued work from continuing with the old configuration.

EmailCopy Anchor Link

On SMTP, enable SMTP email and enter the host, port, sender, and recipient. Port defaults to 587, and Use STARTTLS is on. Username is optional. If authentication is needed, provide the name of an environment variable containing the password.

The subject is Pngr — <event kind>; the body includes the timestamp, message, and session ID. The editor accepts one sender and one recipient email address.

WebhooksCopy Anchor Link

On Webhook, enable webhook POST and choose Webhook format:

Existing configurations without a format stay Generic JSON. Switching formats does not change your alert rules. Pngr sends directly from your computer, without a relay service.

Generic JSONCopy Anchor Link

Supply an HTTP or HTTPS URL and, if required by your endpoint, a bearer-token environment variable name. Embedded username/password credentials in the URL are rejected. Use HTTPS for credentials and monitoring data. Pngr posts Content-Type: application/json and preserves the existing event property names and payload:

{
  "Id": "00000000-0000-0000-0000-000000000001",
  "SessionId": "00000000-0000-0000-0000-000000000002",
  "Timestamp": "2026-10-14T12:00:00+00:00",
  "Kind": "Alert",
  "Message": "example.net: Monitoring alert — Average latency exceeds the threshold",
  "AlertRuleId": "example-rule",
  "AcknowledgedAt": null,
  "AcknowledgmentNote": null
}

This is an illustrative event payload. Event kinds delivered by actions are Alert, Recovery, and RouteChange. Generic JSON retains its single-request delivery behavior.

Create a Discord webhookCopy Anchor Link

1. In Discord, open your server's Server Settings → Integrations → Webhooks. You need the Manage Webhooks permission.
2. Create a webhook, give it a name such as Pngr, and choose the text channel that should receive notifications.
3. Select Copy Webhook URL. Keep the URL private: its token authorizes posting to that channel.
4. In Pngr's Webhook tab, select Discord, enable webhook POST, and paste the copied URL.
5. Leave the bearer-token environment variable empty; Discord authenticates through the webhook URL itself.
6. Press Save actions, choose a live target, and press Test enabled actions. The test sends a real alert message.

See Discord's webhook setup guide and webhook API reference.

Use the native incoming webhook URL, rather than a GitHub-compatible /github URL. Pngr accepts HTTPS webhook URLs on discord.com, canary.discord.com, or ptb.discord.com, with a webhook ID and token and no custom port, query parameters, or fragment. Pngr requests confirmation that Discord created the message. Forum/media channels and thread selection are not configurable in Pngr; choose a text channel.

Discord messagesCopy Anchor Link

Embeds include the event type, session ID, event timestamp, and existing event message. Pngr includes the monitored target and alert rule name when they are available from the session and configured rule. The rule ID is used as a fallback; events without a rule omit that field. Long text is shortened to fit Discord's embed limits. Recovery delivery follows Send recovery notifications and actions.

For example, an alert event could display:

Pngr — Alert                       [red]
example.net: Monitoring alert — Average latency 125.0 ms exceeds 100.0 ms
Event type: Alert
Session: 00000000-0000-0000-0000-000000000002
Target: example.net
Alert rule: Monitoring alert
2026-10-14 12:00 UTC

A recovery uses a green embed with the existing recovery description; a route change uses a blue embed with the existing route description. These are illustrative messages, not screenshots. Actual details depend on the generated event. Discord delivery disables mention parsing, including @everyone, @here, users, and roles; alert text does not intentionally ping channel members.

Delivery and retriesCopy Anchor Link

Neither format follows HTTP redirects. Non-success responses are failures; Pngr records an action result without logging the URL, webhook token, response body, or bearer token.

Discord delivery makes up to three requests for HTTP 429 rate limits and 5xx server errors. It respects Discord's Retry-After response header or JSON retry_after value, waiting for the longer value when both are valid. Without a valid retry signal, it waits one second before the first retry and two seconds before the second. Rate-limit waits also apply to subsequent queued events for the same webhook. Retries and their waits share the configured Action timeout; a long requested wait can end in a timeout instead of another request. Permanent errors, such as an invalid or deleted webhook, need a configuration change. There is no retry setting in the UI. Connection failures and action timeouts are reported without retrying; monitoring continues.

See Discord's rate-limit documentation for its retry signals.

Local executableCopy Anchor Link

On Executable, enable the action and provide an absolute executable path, a JSON array of arguments, and an optional absolute working directory. For example, choose /bin/sh on macOS with arguments ["/absolute/path/to/handle-pngr-alert.sh"]. On Windows, select the absolute path to your interpreter or executable and pass its arguments as the same JSON array format.

Pngr launches the executable directly without shell interpolation. Messages are supplied through environment variables:

The legacy variable names are intentional. Output is drained and discarded. A nonzero exit code is a failure; timeout or application exit cancels the process tree. Only enable programs you trust.

Secrets and testingCopy Anchor Link

Webhook URLs are credentials. Pngr stores them in macOS Keychain or Windows Credential Manager, with a secret reference in the workspace. Exported configuration does not contain the URL; after importing a workspace on another computer, enter the webhook URL again. If secure storage is unavailable or access is denied, Pngr reports a failure rather than saving the URL in plaintext. Previously saved plaintext URLs are migrated when the workspace loads or is saved. If migration fails, the original file is retained and webhook delivery is disabled with a warning, while targets and history still load. Restore credential-store access and save the webhook again. Rotate any URL that may have been shared in an older export or backup.

The URL field is masked and becomes blank after saving. Leave it blank to retain the stored URL, paste a new URL to replace it, or select Remove saved webhook URL to remove the credential. Treat the masked URL field as a credential entry. Do not paste webhook URLs into screenshots, support reports, logs, or source control. To rotate a Discord URL, delete the old webhook in Discord and create a replacement, then enter the new URL in Pngr and save/test it. Renaming a webhook or changing its channel does not revoke its token.

For SMTP passwords and generic bearer tokens, Pngr stores environment variable names, not secret values, in the workspace and exported configuration. The variables must be present in Pngr's own process environment; setting one in an unrelated terminal after Pngr starts does not make it available to the running app. A named but missing variable causes the relevant action to fail.

Choose a live target and click Test enabled actions. This saves settings and performs real enabled actions. Check the alert event log for success or failure. Imported workspaces disable native, SMTP, webhook, and executable actions until you explicitly re-enable them.