Site: Planekeeper Docs — Monitor software versions across your stack. Planekeeper tracks releases, gathers version data, and alerts on drift.
Section: Feature Guides > Notifications > Notification Deliveries
Source: https://docs.planekeeper.com/guides/notifications/deliveries/
Title: Notification Deliveries
Author: Planekeeper
Description: Monitor notification delivery status, understand retry behavior, and manage the dead letter queue for failed deliveries.
Word count: 862
Reading time: 5 min

Contents:
- [Delivery statuses](#delivery-statuses)
- [Delivery lifecycle](#delivery-lifecycle)
- [Retry behavior](#retry-behavior)
  - [Non-retryable errors](#non-retryable-errors)
- [Dead letter queue](#dead-letter-queue)
  - [View dead letters](#view-dead-letters)
  - [Retry a dead letter](#retry-a-dead-letter)
- [View delivery history for an alert](#view-delivery-history-for-an-alert)
- [Common delivery issues](#common-delivery-issues)
  - [Endpoint returning 4xx errors](#endpoint-returning-4xx-errors)
  - [Endpoint returning 5xx errors](#endpoint-returning-5xx-errors)
  - [Deliveries stuck in pending](#deliveries-stuck-in-pending)
  - [Delivery succeeded but no message received](#delivery-succeeded-but-no-message-received)
- [Automatic cleanup](#automatic-cleanup)

***

# 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

| Status | Meaning |
|---|---|
| **Pending** | The delivery is queued and waiting to be picked up by the notifier service |
| **In progress** | The notifier has claimed the delivery and is actively sending it |
| **Succeeded** | The webhook endpoint responded with a 2xx status code |
| **Failed** | The delivery attempt failed but retries remain |
| **Dead letter** | All retry attempts have been exhausted, or the error is non-retryable |

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

| Tier | Attempts | Delays | Purpose |
|---|---|---|---|
| Short-term | 1-4 | 10 seconds, 30 seconds, 1 minute, 5 minutes | Recover from brief network blips or temporary errors |
| Mid-term | 5-8 | 15 minutes, 30 minutes, 1 hour, 2 hours | Handle extended service degradation |
| Long-term | 9-12 | 4 hours each | Wait out prolonged outages |

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

> **info:** 
Retry delays include random jitter to prevent all retries from hitting the endpoint at the same moment. Actual delay times will vary slightly from the values above.


### 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.

> **success:** 
Before retrying, fix the underlying issue (update the channel URL, fix authentication headers, etc.). Otherwise the delivery will fail again and return to the dead letter queue after exhausting retries.


## 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](https://docs.planekeeper.com/guides/notifications/templates/)).
- **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.


---

## Related

- Next: [Notification Rules](https://docs.planekeeper.com/guides/notifications/rules/page.md) — Configure notification routing rules to control which alert events go to which channels based on severity and event type.
- Section: [Notifications](https://docs.planekeeper.com/guides/notifications/index.md)