---
sidebar_label: Manage channels
doc_id: 2e8f6b94-c1d3-4a07-b5e9-8d4f2c6a91e0
toc_max_heading_level: 3
description: >-
  List, inspect, update, and delete notification channels, plus troubleshoot
  common delivery issues.
keywords:
  - manage channels
  - update channel
  - delete channel
  - list channels
  - troubleshooting notifications
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Manage notification channels

After [creating notification channels](/docs/notifications/channels), you can list, inspect, update, and delete them through the UI, CLI, or API.


## List channels

Retrieve all notification channels configured for a given resource (NRN).

<Tabs
defaultValue="list-ui"
values={[
{ label: 'UI (Recommended)', value: 'list-ui' },
{ label: 'CLI', value: 'list-cli' },
{ label: 'cURL', value: 'list-curl' },
]}>
<TabItem value="list-ui">

Go to **Platform settings > Notifications > Channels** to see all configured channels. You can filter by resource using the NRN selector at the top.

</TabItem>
<TabItem value="list-cli">

```bash
np notification channel list \
  --nrn "organization=1:account=2:namespace=3"
```

</TabItem>
<TabItem value="list-curl">

```bash
curl -L 'https://api.nullplatform.com/notification/channel?nrn=organization%3D1%3Aaccount%3D2%3Anamespace%3D3' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
```

</TabItem>
</Tabs>

You can optionally filter by channel type by adding the `type` parameter:

```bash
np notification channel list \
  --nrn "organization=1:account=2:namespace=3" \
  --type "slack"
```

The response includes a paginated list of channels with their IDs, types, sources, NRNs, and configurations.

## Read a channel

Retrieve the full details of a specific channel by its ID.

<Tabs
defaultValue="read-ui"
values={[
{ label: 'UI (Recommended)', value: 'read-ui' },
{ label: 'CLI', value: 'read-cli' },
{ label: 'cURL', value: 'read-curl' },
]}>
<TabItem value="read-ui">

Go to **Platform settings > Notifications > Channels** and click on a channel to view its details, including its configuration, filters, and source.

</TabItem>
<TabItem value="read-cli">

```bash
np notification channel read --id 789
```

</TabItem>
<TabItem value="read-curl">

```bash
curl -L 'https://api.nullplatform.com/notification/channel/789' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
```

</TabItem>
</Tabs>


## Update a channel

Modify an existing channel's configuration, filters, source, or NRN scope. Use the [PATCH endpoint](/docs/api/notification-channel-update) with only the fields you want to change.

<Tabs
defaultValue="update-ui"
values={[
{ label: 'UI (Recommended)', value: 'update-ui' },
{ label: 'CLI', value: 'update-cli' },
{ label: 'cURL', value: 'update-curl' },
]}>
<TabItem value="update-ui">

Go to **Platform settings > Notifications > Channels**, click on the channel you want to modify, update the fields, and click **Save**.

</TabItem>
<TabItem value="update-cli">

```bash
np notification channel update --id 789 \
  --body '{
    "filters": {
      "$or": [
        { "action": "scope:stop" },
        { "action": "scope:delete" }
      ]
    }
  }'
```

</TabItem>
<TabItem value="update-curl">

```bash
curl -L -X PATCH 'https://api.nullplatform.com/notification/channel/789' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "filters": {
      "$or": [
        { "action": "scope:stop" },
        { "action": "scope:delete" }
      ]
    }
  }'
```

</TabItem>
</Tabs>

### Common updates

**Change which Slack channel receives notifications:**

```json
{
  "configuration": {
    "channels": ["new-slack-channel-name"]
  }
}
```

**Broaden the NRN scope from application-level to namespace-level:**

```json
{
  "nrn": "organization=1:account=2:namespace=3"
}
```

**Add a source to an existing channel:**

```json
{
  "source": ["approval", "audit"]
}
```

:::note
The `source` field replaces the entire array. Include all sources you want the channel to listen to, not just the new one.
:::


## Delete a channel

Remove a notification channel permanently.

<Tabs
defaultValue="delete-ui"
values={[
{ label: 'UI (Recommended)', value: 'delete-ui' },
{ label: 'CLI', value: 'delete-cli' },
{ label: 'cURL', value: 'delete-curl' },
]}>
<TabItem value="delete-ui">

Go to **Platform settings > Notifications > Channels**, click on the channel, and click **Delete**.

</TabItem>
<TabItem value="delete-cli">

```bash
np notification channel delete --id 789
```

</TabItem>
<TabItem value="delete-curl">

```bash
curl -L -X DELETE 'https://api.nullplatform.com/notification/channel/789' \
  -H 'Authorization: Bearer <token>'
```

</TabItem>
</Tabs>

:::warning
Deleting a channel is permanent and cannot be undone. Any events that would have been routed to this channel will no longer be delivered.
:::


## Troubleshooting

### Notifications aren't arriving

1. **Check the source.** Make sure the channel's `source` matches the type of event you expect. For example, deployment approvals require `"source": ["approval"]`, not `"source": ["audit"]`. See [Sources & actions](/docs/notifications/sources-and-actions) for the full reference.
2. **Check the NRN scope.** If the channel is scoped to a specific application but the event happens at the namespace level, the channel won't receive it. Try broadening the NRN to the namespace or organization level.
3. **Check the filters.** Overly restrictive filters can silently drop events. Remove the `filters` field temporarily to confirm the channel works, then add filters back one at a time.
4. **For Slack channels:** Verify that the nullplatform Slack app is invited to the target Slack channel. Use `/invite @nullplatform` in Slack.
5. **Verify delivery using notification events.** Go to **Platform settings > Notifications > Events** or use the [List events API](/docs/api/notification-event-list) to see whether the event was generated and its delivery status.

### Getting too many notifications

1. **Add filters** to narrow which events reach the channel. For example, filter by action (`"action": "deployment:create"`) or by namespace (`"details.namespace.slug": "production"`).
2. **Narrow the NRN** from organization-level to account or namespace-level to reduce the event scope.
3. **Split into multiple channels** if different teams need different subsets. Each team gets a channel with its own NRN and filters.

### Webhook returns errors

1. **Verify the URL** is correct and reachable from the internet.
2. **Check authorization headers.** If your endpoint requires authentication, make sure the token or API key in the channel's `headers` configuration is valid and not expired.
3. **Test with resend.** Use the [Resend endpoint](/docs/api/notification-event-resend) to replay a notification event to your webhook and inspect the result. See [Notification events](/docs/notifications/event-payloads#resending-a-notification-event) for details.

### Agent channel not triggering

1. **Confirm the agent is running** and connected to nullplatform. The agent must be online and reachable.
2. **Check the API key.** The `api_key` in the channel configuration must have the correct permissions.
3. **Verify the selector.** The `selector` tags on the channel must match the tags assigned to your agent. For example, if the channel specifies `"selector": { "environment": "production" }`, the agent must have the `environment=production` tag.
4. **Check the command path.** The `cmdline` in the channel configuration must point to a valid executable on the agent's machine.


## Next steps

- [Create a new channel](/docs/notifications/channels)
- [Learn about sources and actions](/docs/notifications/sources-and-actions)
- [Inspect event payloads and resend notifications](/docs/notifications/event-payloads)