# Update an alert channel — API reference

> Updates an alert channel's display name, scope or type-specific configuration.

Source: https://upfour.io/docs/api/notification-channels/update-an-alert-channel

[Developers](https://upfour.io/docs/api.md)/[Alert channels](https://upfour.io/docs/api/notification-channels.md)

Updates an alert channel's display name, scope or type-specific configuration.

PUT https://app.upfour.io/v1/notification_channels/{channelID}

scope notification_channel.write stable returns 200

## Parameters

| Field | Type | Description |
| --- | --- | --- |
| `channelID` required | uuid | path parameter |

## Body

`application/json` required 5 fields

All other fields56 fields

client_iduuid · nullable

configobject

Only the keys of the channel's type are read. Secret keys left empty or sent back as the masked value keep the stored secret; an empty object or null keeps the whole config.

Possible shapes 16

`email` · object

type email.

| Field | Type | Description |
| --- | --- | --- |
| `email` required | string | Recipient email address. In the app: **Email address** |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |
| `send_individually` optional | boolean | Skip the digest for this channel and send every notification on its own. In the app: **Send every notice on its own** |

`sms` · object

type sms (Twilio).

| Field | Type | Description |
| --- | --- | --- |
| `account_sid` required | string | Twilio Account SID. |
| `auth_token` required | string | Twilio Auth Token of that region and account. Secret. |
| `from_number` required | string pattern `^\+[0-9]{7,15}$` | Sender number in E.164 format. |
| `to_number` required | string pattern `^\+[0-9]{7,15}$` | Recipient number in E.164 format. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |
| `region` optional | string one of`us1` `ie1` `""` | Twilio region of the account; empty means us1\. ie1 does not take numbers starting with +1. |

`voice` · object

type voice (Twilio phone call).

| Field | Type | Description |
| --- | --- | --- |
| `account_sid` required | string pattern `^AC[0-9a-fA-F]{32}$` | Twilio Account SID (AC followed by 32 hex digits). |
| `auth_token` required | string min length 16 | Twilio Auth Token of that region and account, without surrounding spaces. Secret. |
| `from_number` required | string pattern `^\+[0-9]{7,15}$` | Sender number in E.164 format. |
| `to_number` required | string pattern `^\+[0-9]{7,15}$` | Recipient number in E.164 format. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |
| `region` optional | string one of`us1` `ie1` `au1` `""` | Twilio region of the account; empty means us1. |

`webhook` · object

type webhook.

| Field | Type | Description |
| --- | --- | --- |
| `url` required | string (uri) pattern `^https://` | https URL that receives the alert. In the app: **Webhook URL** |
| `secret` optional | string | Signs the request in X-Up4-Signature when set. Secret. In the app: **Signing secret** |

`slack` · object

type slack.

| Field | Type | Description |
| --- | --- | --- |
| `webhook_url` required | string (uri) pattern `^https://` | Incoming-webhook URL; the host must end in slack.com. Secret. In the app: **Slack Webhook URL** |
| `channel` optional | string | Channel to post to, if the webhook allows overriding it. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |

`telegram` · object

type telegram.

| Field | Type | Description |
| --- | --- | --- |
| `bot_token` required | string | Token of the Telegram bot. Secret. In the app: **Bot Token** |
| `chat_id` required | string | Chat, group or channel ID the bot posts to. In the app: **Chat ID** |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |

`msteams` · object

type msteams.

| Field | Type | Description |
| --- | --- | --- |
| `webhook_url` required | string (uri) pattern `^https://` | Incoming-webhook URL of the Teams channel. Secret. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |

`discord` · object

type discord.

| Field | Type | Description |
| --- | --- | --- |
| `webhook_url` required | string (uri) pattern `^https://` | Discord webhook URL. Secret. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |

`pagerduty` · object

type pagerduty.

| Field | Type | Description |
| --- | --- | --- |
| `routing_key` required | string | Integration (routing) key of the PagerDuty service. Secret. In the app: **Routing Key** |

`zapier` · object

type zapier.

| Field | Type | Description |
| --- | --- | --- |
| `webhook_url` required | string (uri) pattern `^https://` | Zapier catch-hook URL. Secret. |

`datadog` · object

type datadog.

| Field | Type | Description |
| --- | --- | --- |
| `api_key` required | string | Datadog API key. Secret. |
| `region` optional | string one of`us1` `eu1` `us3` `us5` `ap1` `""` | Datadog site; empty means us1. |

`newrelic` · object

type newrelic.

| Field | Type | Description |
| --- | --- | --- |
| `account_id` required | string | New Relic account ID. |
| `license_key` required | string | New Relic license key. Secret. |
| `region` optional | string one of`us` `eu` `""` | New Relic data centre; empty means us. |

`jira` · object

type jira.

| Field | Type | Description |
| --- | --- | --- |
| `api_token` required | string | Jira API token. Secret. |
| `base_url` required | string (uri) pattern `^https://` | https URL of the Jira site. |
| `email` required | string | Account email of the API token. |
| `issue_type` required | string | Issue type to create, e.g. Bug, Task or Story. |
| `project_key` required | string pattern `^[A-Z][A-Z0-9_]{0,19}$` | Key of the project that receives the issues. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |

`grafana` · object

type grafana.

| Field | Type | Description |
| --- | --- | --- |
| `webhook_url` required | string (uri) pattern `^https?://` | Grafana webhook URL, http or https. Secret. |

`ntfy` · object

type ntfy.

| Field | Type | Description |
| --- | --- | --- |
| `topic` required | string pattern `^[-_A-Za-z0-9]{1,64}$` | Topic to publish to. |
| `access_token` optional | string | Access token of a protected topic. Secret. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |
| `priority` optional | string | min, low, default, high, max, urgent or 1 to 5. |
| `server_url` optional | string (uri) pattern `^https://` | HTTPS origin of the ntfy server without credentials, query or fragment; empty means https://ntfy.sh. |

`pushover` · object

type pushover.

| Field | Type | Description |
| --- | --- | --- |
| `app_token` required | string pattern `^[A-Za-z0-9]{30}$` | 30-character Pushover application token. Secret. |
| `user_key` required | string pattern `^[A-Za-z0-9]{30}$` | 30-character Pushover user or group key. Secret. |
| `device` optional | string | Device name to send to; empty reaches every device. |
| `language` optional | string one of`en` `de` `""` | Language of the notifications; empty inherits the company language. |
| `priority` optional | integer \-2–1 | Pushover priority from -2 to 1; emergency priority is not supported. |

namestring

A new display name; empty keeps the current one.

In the app: **Name**

scopestring · nullable

Changes the scope together with client_id or team_id; leave all three out to keep it.

organizationclientteam

team_iduuid · nullable

## Returns

A successful request returns `200` with application/json.

Response fields 1 top-level fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | NotificationChannelResponse | |
| NotificationChannelResponse · 17 fields FieldTypeDescription `config` object free-form keys The keys of the channel's type as sent on create. Secret values (auth_token, secret, webhook_url, bot_token, routing_key, api_key, license_key, api_token, app_token, user_key, access_token) are masked: \*\*\*\*\*\* followed by their last four characters when longer than eight characters, otherwise only \*\*\*\*\*\*. `created_at` string (date-time) `id` uuid `monitor_count` integer Monitors that route to this channel; 0 means nothing uses it. Only filled in the list. `name` string `scope` string one of`organization` `client` `team` `type` string one of`email` `sms` `voice` `webhook` `slack` `telegram` `msteams` `discord` `pagerduty` `zapier` `datadog` `newrelic` `jira` `grafana` `ntfy` `pushover` `updated_at` string (date-time) `user_id` uuid `client_id` uuid `last_delivery_at` string (date-time) Last successful delivery. Filled in the list. `last_failure_at` string (date-time) Last failed delivery attempt. Filled in the list. `last_failure_reason` string `last_voice_at` string (date-time) `last_voice_status` string Status of the last phone call, voice channels only. Filled in the list. `organization_id` uuid Company the channel belongs to. `team_id` uuid | | |

## Errors

Only the errors this operation can return. Every error uses the [same envelope](https://upfour.io/docs/api/responses.md).

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | [bad_request](https://upfour.io/docs/api/errors#code-bad_request) | The request is malformed or fails validation. |
| 404 | [not_found](https://upfour.io/docs/api/errors#code-not_found) | The requested resource does not exist or is outside the caller's scope. |
| 403 | [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) | The credentials do not permit this action. |

Every call can also return `unauthorized` (401), `rate_limit_exceeded` (429) or `internal_error` (500 / 502). See [Responses and errors](https://upfour.io/docs/api/responses.md).

[PreviousGet an alert channel](https://upfour.io/docs/api/notification-channels/get-an-alert-channel.md) [NextDelete an alert channel](https://upfour.io/docs/api/notification-channels/delete-an-alert-channel.md)

## Request

### cURL

```bash
curl -s -X PUT "https://app.upfour.io/v1/notification_channels/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "email": "oncall@example.com"
    },
    "name": "On-call email",
    "type": "email"
  }'
```

### JavaScript

```javascript
const res = await fetch("https://app.upfour.io/v1/notification_channels/00000000-0000-4000-8000-000000000001", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.UP4_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    config: {
      email: "oncall@example.com",
    },
    name: "On-call email",
    type: "email",
  }),
});
console.log(res.status, await res.json());
```

### Python

```python
import os
import requests

res = requests.put(
    "https://app.upfour.io/v1/notification_channels/00000000-0000-4000-8000-000000000001",
    headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"},
    json={
        "config": {
            "email": "oncall@example.com",
        },
        "name": "On-call email",
        "type": "email",
    },
)
print(res.status_code, res.json())
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
  "config": {
    "email": "oncall@example.com"
  },
  "name": "On-call email",
  "type": "email"
}`)
	req, _ := http.NewRequest("PUT", "https://app.upfour.io/v1/notification_channels/00000000-0000-4000-8000-000000000001", payload)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}
```

### PHP

```php
<?php
$payload = <<<'JSON'
{
  "config": {
    "email": "oncall@example.com"
  },
  "name": "On-call email",
  "type": "email"
}
JSON;

$ch = curl_init("https://app.upfour.io/v1/notification_channels/00000000-0000-4000-8000-000000000001");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("UP4_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n";
curl_close($ch);
```

## Response

### 200

```json
{
  "data": {
    "config": {
      "email": "oncall@example.com"
    },
    "created_at": "2026-10-27T09:00:00Z",
    "id": "00000000-0000-4000-8000-000000000001",
    "monitor_count": 0,
    "name": "On-call email",
    "organization_id": "00000000-0000-4000-8000-000000000002",
    "scope": "organization",
    "team_id": "00000000-0000-4000-8000-000000000003",
    "type": "email",
    "updated_at": "2026-10-27T09:00:00Z",
    "user_id": "00000000-0000-4000-8000-000000000004"
  }
}
```

### 400

```json
{
  "error": {
    "code": "bad_request",
    "message": "The request is malformed or fails validation.",
    "request_id": "req_…"
  }
}
```

### 403

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credentials do not permit this action.",
    "request_id": "req_…"
  }
}
```

### 404

```json
{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist or is outside the caller's scope.",
    "request_id": "req_…"
  }
}
```