Notification Deliveries

Every notification Planekeeper sends is tracked as a delivery record. The deliveries page shows the status of each notification attempt, including successful deliveries, in-flight retries, and failures that have exhausted their retry budget.

Delivery statuses

Delivery lifecycle

A typical delivery follows this path:

Pending ──> In Progress ──> Succeeded
                 |
                 |  (error or timeout)
                 v
              Failed ──> In Progress ──> Succeeded
                 |
                 |  (max retries exceeded)
                 v
            Dead Letter

Most deliveries reach Succeeded on the first attempt. When an endpoint is temporarily unavailable, the delivery enters a retry loop between Failed and In Progress until it succeeds or runs out of attempts.

Retry behavior

When a delivery fails, Planekeeper retries it with exponential backoff across three tiers:

The total retry window spans approximately 24 hours from the first attempt. After the final attempt, the delivery moves to the dead letter queue.

Non-retryable errors

Some failures skip the retry cycle entirely and go straight to the dead letter queue:

• 4xx responses (except 429 Too Many Requests) indicate a problem with the request itself, not a transient failure. Retrying will not help.
• Invalid channel configuration such as a malformed URL.

A 429 Too Many Requests response is retryable. Planekeeper honors the Retry-After header if the endpoint provides one.

Dead letter queue

The dead letter queue holds deliveries that could not be successfully sent after all retry attempts. You can view and retry dead letters directly from the UI.

View dead letters

1. Navigate to Notifications > Deliveries in the sidebar.
2. Click the Dead Letters tab to see all deliveries that exhausted their retry budget.

Each dead letter shows the channel name, event type, last error message, number of attempts, and when it was last tried.

Retry a dead letter

1. Find the failed delivery in the dead letter list.
2. Click the Retry button on the delivery row.
3. The delivery is re-queued as a new pending delivery and will be picked up by the notifier service.

View delivery history for an alert

The alert detail page shows all notification deliveries associated with a specific alert. To view delivery history:

1. Navigate to Alerts in the sidebar.
2. Click an alert to open its detail page.
3. Scroll down to the Delivery History section.

The delivery history table shows each notification attempt, including the channel name, event type (created, escalated, acknowledged, resolved), status, number of attempts, HTTP response code, and timestamp. This helps you verify that notifications were sent and troubleshoot any delivery failures for a specific alert.

You can also query delivery history via the API: GET /alerts/{id}/deliveries.

Common delivery issues

Endpoint returning 4xx errors

A 4xx status code means the request is being rejected by the receiving service. Common causes:

• 401/403: Authentication headers are missing or expired. Update the channel’s custom headers or API key.
• 400: The payload format is wrong for the target platform. Review your template against the platform’s expected format (see templates guide).
• 404: The webhook URL is incorrect or the endpoint was deleted. Update the channel URL.

Endpoint returning 5xx errors

A 5xx status code means the receiving service has an internal error. These are retryable – Planekeeper will keep trying according to the retry schedule. If the issue persists for 24 hours, the delivery moves to the dead letter queue.

Deliveries stuck in pending

If deliveries stay in Pending for more than a few minutes, verify that the notifier service is running and healthy. The notifier polls for pending deliveries every few seconds. Check the service health on the dashboard.

Delivery succeeded but no message received

If the delivery status shows Succeeded but the message did not appear in your target service:

• Check the channel’s webhook URL points to the correct workspace/channel.
• Verify the template produces a valid payload for the target platform. Some services accept the HTTP request (200 OK) but silently drop malformed messages.
• Test the channel to see what payload is being sent.

Automatic cleanup

Planekeeper automatically manages old delivery records:

• Succeeded deliveries older than 30 days are purged automatically.
• Expired pending deliveries stuck for more than 24 hours are moved to the dead letter queue.
• Acknowledgment tokens expire after 24 hours and are cleaned up periodically.

This keeps the deliveries table manageable without manual intervention.