Skip to content
Planekeeper is currently in alpha development. Features and APIs may change. Feedback is welcome!
Request early access to get started.

Notification Channels

A notification channel defines where Planekeeper sends alert notifications. Each channel points to an external endpoint -- a webhook URL, a Discord channel, a Slack workspace, or another service -- and holds the configuration needed to deliver messages there.

Supported channel types

Type Description
Webhook Send HTTP POST requests to any URL that accepts JSON payloads
Discord Send messages to a Discord channel via its webhook URL
Slack Send messages to a Slack channel via an incoming webhook
PagerDuty Trigger and resolve incidents via the PagerDuty Events API
Telegram Send messages via the Telegram Bot API
SMTP Send email notifications

Note

Webhook is the primary channel type today. Discord, Slack, PagerDuty, Telegram, and SMTP use the webhook type with platform-specific templates to format messages correctly for each service. See the templates guide for platform-specific configuration.

Create a channel

  1. Navigate to Notification Channels in the sidebar.
  2. Click Create Channel.

  3. Fill in the form:

    Field Description
    Name A descriptive label, e.g., "Production Slack Alerts"
    Type Select the channel type
    URL The webhook endpoint URL
    HMAC Secret Optional. A shared secret for signing payloads (see signature verification)
    Require login to acknowledge When checked, users must be logged in to acknowledge alerts via the link in notifications. When unchecked, anyone with the link can acknowledge anonymously. See acknowledgment authentication. Default: checked

  4. Click Save.

Tip

Name channels after their destination and purpose: "Discord - Critical Alerts", "Ops Team Slack", "PagerDuty Production". This makes it easy to identify channels when configuring notification rules.

Test a channel

Before relying on a channel for production alerts, verify it works.

  1. Navigate to Notification Channels.
  2. Click the channel you want to test.
  3. Click Test Channel.

The test sends a sample notification payload to the configured URL and reports the result:

  • Success: The endpoint responded with a 2xx status code.
  • Failure: The test shows the HTTP status code and response body to help you diagnose the issue.

Warning

Test notifications use a synthetic alert payload. The message will appear in your target service (Slack, Discord, etc.) as a real-looking notification with sample data.

Toggle a channel on or off

Each channel has an active/inactive toggle. Click the toggle badge on the channels list to switch the state.

  • Active channels receive notifications when matched by notification rules.
  • Inactive channels are skipped during delivery. No notifications are sent to them.

Deactivating a channel does not delete pending deliveries. Any in-flight retries for the channel will continue until they succeed or exhaust their retry budget.

Default channel

One channel per organization can be designated as the default. The default channel is used when a notification rule does not specify a particular channel override.

Set the default channel from the Notification Channels list or from the notification settings page.

Tip

Always configure a default channel. Notification rules that rely on the default will silently skip delivery if no default is set.

HMAC signature verification

When you configure an HMAC secret on a channel, Planekeeper signs every outbound webhook payload. Use this to verify that incoming webhooks on your receiving service actually came from Planekeeper.

How it works:

  1. Planekeeper computes an HMAC-SHA256 signature over the payload using the shared secret.
  2. The signature is included in the X-Planekeeper-Signature header as sha256={hmac}.
  3. The current Unix timestamp is included in the X-Planekeeper-Timestamp header.

To verify on your receiving end:

  1. Read the X-Planekeeper-Timestamp and request body.
  2. Compute HMAC-SHA256(secret, timestamp + "." + body).
  3. Compare your computed signature with the value in X-Planekeeper-Signature.

Note

The signature covers both the timestamp and the body to prevent replay attacks. Reject requests with timestamps older than a few minutes.

Acknowledgment authentication

Each channel controls whether acknowledge links require a logged-in user session. This is the Require login to acknowledge alerts checkbox on the channel form.

Authenticated acknowledgments (default)

When enabled (the default), clicking an acknowledge link in a notification redirects the user to the Planekeeper login page if they do not have an active session. After login, they are sent back to the acknowledge URL to complete the action.

This mode records who acknowledged the alert — the user's identity is attached to the acknowledgment record.

Anonymous acknowledgments

When disabled, anyone with the acknowledge link can acknowledge the alert without logging in. No user identity is recorded.

Use anonymous acknowledgments when:

  • Notifications go to a shared channel (Discord, Slack) where multiple people may click the link
  • You have programmatic consumers (bots, automation) that call the acknowledge URL
  • Your team does not use Planekeeper login and only interacts through notifications

Warning

Anonymous acknowledge links can be triggered by anyone who has the URL. Keep your notification channels private if you disable this setting.

Tip

Link-preview bots (Discord, Slack, Teams) will not accidentally trigger acknowledgments. Planekeeper uses a two-step process: the GET request serves an HTML page that requires a form submission (POST) to complete the acknowledgment.

Standard webhook headers

Every webhook delivery includes these headers:

Header Description
Content-Type application/json
X-Planekeeper-Event The event type (e.g., alert.created)
X-Planekeeper-Idempotency-Key A unique ID for this delivery, stable across retries
X-Planekeeper-Signature HMAC signature (only if secret is configured)
X-Planekeeper-Timestamp Unix timestamp of the request
User-Agent Planekeeper-Notifier/1.0

You can also add custom headers in the channel configuration for services that require specific authentication headers.

URL restrictions

Webhook URLs must point to public endpoints by default. Planekeeper blocks private IP ranges, localhost, and link-local addresses to prevent misuse.

If you need to send webhooks to internal services (for testing or private deployments), an administrator can enable private URL delivery in the system configuration.

Bulk delete

Select multiple channels using the checkboxes on the list page, then click Delete Selected to remove them in a single operation. Use the checkbox in the table header to select all visible items. Notification rules that referenced deleted channels will fall back to the default channel.

Delete a channel

  1. Navigate to Notification Channels.
  2. Click the channel you want to remove.
  3. Click Delete.

Warning

Deleting a channel removes it permanently. Any notification rules that reference this channel will fall back to the default channel. Pending deliveries for the deleted channel are not retried.