Skip to Content
Uptimeify Docs
Notification channels

List Notification Channels

Returns notification channels scoped by organization, customer, or website.

GET /api/notification-channels

Query Parameters

ParameterTypeRequiredDescription
organizationIdnumberNoScope to organization
customerIdnumberNoScope to customer
websiteIdnumberNoScope to website (includes org + customer channels)
envelopestringNoitems: answer as { items, total, page, perPage }. Becomes the default on 2027-01-18.

Example (cURL)

curl -X GET "$BASE_URL/api/notification-channels?organizationId=1&envelope=items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response

{
  "items": [
    {
      "id": 1,
      "organizationId": 1,
      "customerId": null,
      "websiteId": null,
      "type": "email",
      "category": "direct",
      "name": "Ops Email",
      "config": { "email": "ops@deinkunde.com", "to": "Ops Team" },
      "delaySeconds": 0,
      "conditions": null,
      "isActive": true,
      "allowedPackageTypes": null
    },
    {
      "id": 2,
      "organizationId": 1,
      "customerId": null,
      "websiteId": null,
      "type": "slack",
      "category": "integration",
      "name": "Alerts Slack Channel",
      "config": { "webhookUrl": null, "hasWebhookUrl": true, "username": "Uptimeify" },
      "delaySeconds": 0,
      "conditions": null,
      "isActive": true,
      "allowedPackageTypes": null
    }
  ],
  "total": 2,
  "page": 1,
  "perPage": 2
}

List form: with envelope=items the list arrives as { items, total, page, perPage }. Without it the endpoint still answers the current form (a bare array of the same items), which is deprecated; { items, ... } becomes the default on 2027-01-18.

Secrets inside config are never returned: a Slack, Discord or Teams webhook URL comes back as null with hasWebhookUrl: true next to it, see "Channel Types and Config" on the Notification Channels overview page.

Custom HTTP headers (config.headers, config.webhookHeaders) keep their names but never return their values: { "X-Api-Key": null }, with hasHeaders: true in config. Values are stored encrypted. Until 20.10.2026 the values came back in plain text.

Visibility

Without websiteId and without customerId, which channels come back depends on who is reading:

  • An unrestricted reader (organization admin, global admin, and an organization-bound agent token) receives the organization-level channels, that is those with customerId: null and websiteId: null.
  • A customer-scoped reader (a readonly user or an editor with explicit customer assignments, plus the API or agent token minted for such a user) receives the channels of their own customers in addition to the organization-level ones. Channels of another customer are never returned.

Naming customerId returns that customer's channels plus the organization-level ones. Naming websiteId additionally returns the website's own override channels.

Common errors

  • 401 Unauthorized when not authenticated
  • 403 Forbidden when accessing channels outside your scope

On this page