Settings

Create a new Setting

Creates an immutable webhook configuration.

Authentication: Inline vs Shared

Inline (Recommended):

  • Credentials directly in Setting (source: INLINE)
  • Use when: Each Setting has unique credentials

Shared (Advanced):

  • Multiple Settings share one AuthProfile resource (source: REFERENCE)
  • Use when: Centralizing credentials, managing one AuthProfile instead of duplicating across Settings

Immutability

Settings are immutable (except friendlyName, description).

To change configuration: Create new Setting → Update Rule → Delete old Setting.

This enables safe testing before production cutover.

post/v1/Webhooks/Settings

Request

  • Base URL
    https://webhooks.twilio.com
  • Auth
    HTTP basic

Headers

Idempotency-Keystring uuid

Idempotency key for mutation operations. Must be a UUIDv7 (other UUID versions are rejected with a 400).

Request body

friendlyNamestring nullable

Human-readable name (optional, defaults to blank)

descriptionstring

Optional description of the Setting's purpose and usage

Example request

{
  "edgeZones": {
    "zones": [
      "eu",
      "na"
    ]
  }
}

Response

Setting created

idstring 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
friendlyNamestring required

Human-readable name

descriptionstring

Optional description of the Setting's purpose and usage

createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "edgeZones": {
    "zones": [
      "eu",
      "na"
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.