---
title: "Update Setting friendlyName and description"
method: PATCH
path: "/v1/Webhooks/Settings/{settingId}"
tags: ["Settings"]
---

# Update Setting friendlyName and description

`PATCH /v1/Webhooks/Settings/{settingId}`

## Request

- Base URL: `https://webhooks.twilio.com`
- URL: `https://webhooks.twilio.com/v1/Webhooks/Settings/{settingId}`
- Auth: HTTP basic

Updates only the friendlyName and/or description fields. Settings are immutable except for these fields.
To change configuration (auth, signature, connection, etc.), create a new Setting resource.
Returns 409 Conflict if attempting to modify a system-created Setting.

## Request body

- PatchSetting: Request body for PATCH Setting - only friendlyName and description can be updated
  - `friendlyName` string: Human-readable name
  - `description` string: Optional description of the Setting's purpose and usage

## Response `200`

Setting updated successfully

- Setting: Reusable webhook configuration combining auth, signing, and connection settings
  - `id` string, required: Unique Setting identifier (TypeID/TTID format)
  - `type` 'SYSTEM' | 'CUSTOMER', required: Setting ownership (read-only): - **system**: Managed by Twilio - Twilio provides managed Settings to simplify your onboarding journey - Cannot be modified or deleted - Used for default account configuration - **customer**: Created by you - Can update friendlyName via PATCH - Can delete via DELETE (if not in use) - Core config (auth, signature) is immutable
  - `friendlyName` string, required: Human-readable name
  - `description` string: Optional description of the Setting's purpose and usage
  - `auth` union: Authentication configuration for Settings. Discriminated by 'source' field: - source: INLINE → credentials embedded in 'value' object; 'value.scheme' selects the auth type - source: REFERENCE → references an AuthProfile resource via authProfileId
    - InlineAuth: Inline credentials embedded in the Setting. Credentials are in the 'value' object, discriminated by 'value.scheme'.
      - `source` 'INLINE', required
      - `value` union, required: Credential payload, discriminated by 'scheme'.
        - OAuth2Credentials: OAuth2 client credentials
          - `scheme` 'OAUTH2', required
          - `tokenUrl` string, uri, required: OAuth2 token endpoint URL
          - `clientId` string, required: OAuth2 client identifier
          - `clientSecret` string: OAuth2 client secret (write-only, never returned)
          - `scope` string: OAuth2 scope to request
          - `audience` string: OAuth2 audience parameter
          - `clientCredentialsAuthMethod` 'CLIENT_SECRET_POST' | 'CLIENT_SECRET_BASIC': Client credentials authentication method (defaults to CLIENT_SECRET_POST)
        - BasicCredentials: HTTP Basic auth credentials
          - `scheme` 'BASIC', required
          - `username` string, required
          - `password` string: Password (write-only, never returned)
        - DigestCredentials: HTTP Digest auth credentials
          - `scheme` 'DIGEST', required
          - `username` string, required
          - `password` string: Password (write-only, never returned)
        - NoCredentials: Explicitly disables authentication
          - `scheme` 'NONE', required
    - AuthProfileRef: References an AuthProfile resource. Use source: REFERENCE when multiple Settings share the same auth profile. The auth scheme is determined by the referenced AuthProfile resource.
      - `source` 'REFERENCE', required: Indicates credentials come from an AuthProfile resource
      - `authProfileId` string, required: AuthProfile resource ID (TypeID/TTID format)
  - `signature` union: Webhook request signing configuration. Uses discriminator on 'type' field to determine required properties. Use type: none to explicitly disable signing.
    - object: Signature configuration using a SharedKey. The sharedKeyId references a SharedKey resource for signing webhook requests.
      - `type` 'SHARED_KEY', required: Indicates SharedKey-based signing
      - `sharedKeyId` string, required: SharedKey SID to use for signing
      - `algorithm` 'HMAC_SHA1' | 'HMAC_SHA256', required: Signing algorithm used to compute the request signature. Must be specified when creating a signature configuration via the v2 API; not modifiable afterward.
    - object: Signature configuration using the Twilio account auth token. **Legacy:** This method couples signing to the master account credential. It is supported for existing integrations but new integrations should use `SHARED_KEY` instead, which provides security isolation and supports key rotation without touching account credentials.
      - `type` 'ACCOUNT_AUTH_TOKEN', required: Indicates account auth token signing (legacy — prefer SHARED_KEY)
      - `algorithm` 'HMAC_SHA1' | 'HMAC_SHA256', required: Signing algorithm used to compute the request signature. Must be specified when creating a signature configuration via the v2 API; not modifiable afterward.
    - object: Explicitly indicates no request signing
      - `type` 'NONE', required: Indicates no signing
  - `connection` ConnectionSetting: HTTP connection settings for webhook requests
    - `connectTimeoutMs` integer, required: TCP connection timeout in milliseconds (100ms - 15s)
    - `readTimeoutMs` integer, required: Response read timeout in milliseconds (100ms - 15s)
    - `totalTimeoutMs` integer: Total request timeout including retries (100ms - 60s). Optional.
    - `retryPolicy` RetryPolicy: Retry behavior for failed webhook requests. If not specified, no retries are attempted (retryCount: 0 is the default).
      - `retryCount` integer, required: Number of retry attempts (default: 0, no retries)
      - `retryOn` string[], required: Conditions that trigger retries: - HTTP_4XX: Retry on 4xx HTTP status codes - HTTP_5XX: Retry on 5xx HTTP status codes - CONNECTION_TIMEOUT: Retry on TCP/TLS connection failures - READ_TIMEOUT: Retry when server doesn't respond in time - ALL: Retry on all failure types
  - `edgeZones` EdgeZones: Edge zone configuration for webhook delivery. Omitting this field means all zones are eligible and Twilio selects freely.
    - `zones` string[], required: Priority-ordered list of zone IDs. Twilio routes to the first available zone in order. Individual PoP identifiers (e.g. `IAD-1`) are not valid — use zone IDs only (see `GET /EdgeZones` for available values).
    - `allowZoneFallback` boolean: Controls delivery when none of the configured zones have available PoPs. - `false` (default): delivery fails rather than routing through an unconfigured zone. - `true`: Twilio falls back to any available zone outside the configured list.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: Validation error (friendlyName or description exceeds maximum length)
- `401`: Authentication failed
- `403`: Authenticated account does not have permission to perform this operation
- `404`: Setting not found
- `409`: Cannot modify or delete system-created Settings
- `429`: Rate limit exceeded
- `500`: An unexpected server error occurred

---

[API](https://skmtc.dev/twilio/apis/webhooks-v1.md) - [All operations](https://skmtc.dev/twilio/apis/webhooks-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/twilio/apis/webhooks-v1/revisions/629b4cc3a029?raw)
