---
title: "Update Rule (async)"
method: PATCH
path: "/v1/Webhooks/Rules/{ruleId}"
tags: ["Rules"]
---

# Update Rule (async)

`PATCH /v1/Webhooks/Rules/{ruleId}`

## Request

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

Updates rule configuration. Returns 202 Accepted, propagates in 30-60 seconds.

### Gradual Rollout Pattern

Test configuration changes with production traffic before full deployment.

**Strategy:** Gradually shift traffic to new Setting, monitor, increase to 100%.

**Flow:** 90/10 → 50/50 → 0/100 (rollback to 100/0 if issues)

### During Propagation

During propagation (~30-60s), webhooks may use previous or updated config until change is active.

### Use Cases

- **Credential rotation**: Verify new auth works before full cutover
- **Timeout tuning**: Test connection settings with real traffic

### What Can Change

- `friendlyName`, `description`: Metadata
- `settings`: Traffic distribution (percentages must sum to 100)
- `matchType` + its companion value (`prefix` or `value`): changes the rule's match type and value together (async, same 30-60s propagation as any other patch). Returns `409` if the new match key collides with another Rule, same check `POST` runs on create. Patching a Rule to the match config it already has is not a collision.

## Headers

- `Idempotency-Key` string, uuid

## Request body

- union: Request body for PATCH Rule - partially updates the rule. Omit matchType to leave match config unchanged (metadata/settings-only update). Include matchType to change match type and value together (requires the companion field for that type).
  - PatchPrefixMatchRule
    - `friendlyName` string: Human-readable name for the Rule
    - `description` string: Optional description of the Rule's purpose and usage
    - `matchType` 'PREFIX_MATCH', required
    - `prefix` string, required: New URL prefix to match, MUST be unique across all prefix match rules and MUST end with `/`.
    - `settings` SettingReference[]: Settings to apply with traffic distribution (percentages must sum to 100)
      - `settingId` string, required: Setting resource ID (TypeID format)
      - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)
  - PatchExactMatchRule
    - `friendlyName` string: Human-readable name for the Rule
    - `description` string: Optional description of the Rule's purpose and usage
    - `matchType` 'EXACT_MATCH', required
    - `value` string, required: New exact URL to match, MUST be unique across all exact match rules and MUST NOT end with `/`.
    - `settings` SettingReference[]: Settings to apply with traffic distribution (percentages must sum to 100)
      - `settingId` string, required: Setting resource ID (TypeID format)
      - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)
  - PatchDefaultRule: Switches (or keeps) the rule as the account's default rule. Only one default rule allowed per account.
    - `friendlyName` string: Human-readable name for the Rule
    - `description` string: Optional description of the Rule's purpose and usage
    - `matchType` 'DEFAULT', required
    - `settings` SettingReference[]: Settings to apply with traffic distribution (percentages must sum to 100)
      - `settingId` string, required: Setting resource ID (TypeID format)
      - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)
  - PatchMetadataOnlyRule: No matchType field - leaves current match config (matchType/prefix/value) unchanged.
    - `friendlyName` string: Human-readable name for the Rule
    - `description` string: Optional description of the Rule's purpose and usage
    - `settings` SettingReference[]: Settings to apply with traffic distribution (percentages must sum to 100)
      - `settingId` string, required: Setting resource ID (TypeID format)
      - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)

## Response `202`

Rule update accepted

- RuleOperationResponse: Response body for async Rule operations (202 Accepted). Contains the Operation tracking object and, for create/update, the Rule state. For delete operations, `rule` is omitted since the resource is being removed.
  - `operation` Operation, required: Tracks status of async Rule operations
    - `id` string, required: Unique operation identifier (TypeID/TTID format)
    - `statusUrl` string, uri, required: URL to poll for operation status (same as Location header in 202 response)
    - `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'CANCELLED' | 'FAILED', required: Current state of the operation: - PENDING: Accepted, not yet started - RUNNING: Propagating to all regions (typically 30-60 seconds) - COMPLETED: Rule active globally - CANCELLED: Operation was cancelled before completion - FAILED: Operation could not complete; see error field for details
    - `error` OperationError
      - `type` string, uri, required: URI identifying the problem type
      - `title` string, required: Short human-readable summary of the problem type
      - `code` integer, required: Twilio-specific numeric error code
      - `detail` string, required: Human-readable explanation specific to this occurrence
    - `resourceId` string: ID of the affected resource
    - `createdAt` string, date-time, required
    - `completedAt` string, date-time
    - `retentionPeriod` string, duration, required: ISO-8601 duration for how long this Operation record is retained after creation (fixed at 7 days)
  - `rule` union: URL matching rule that applies Settings to webhook requests. Rules are discriminated by matchType - each type has different required fields.
    - PrefixMatchRule: Rule that matches URLs starting with a prefix
      - `id` string, required: Unique Rule identifier (TypeID/TTID format)
      - `friendlyName` string: Human-readable name for identification
      - `description` string: Optional description of the Rule's purpose and usage
      - `matchType` 'PREFIX_MATCH', required
      - `settings` SettingReference[], required: Settings to apply with traffic distribution (percentages must sum to 100)
        - `settingId` string, required: Setting resource ID (TypeID format)
        - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `prefix` string, required: URL prefix to match. Must be unique - only one rule per prefix allowed. Example: 'https://api.example.com/webhooks/'
    - ExactMatchRule: Rule that matches an exact URL
      - `id` string, required: Unique Rule identifier (TypeID/TTID format)
      - `friendlyName` string: Human-readable name for identification
      - `description` string: Optional description of the Rule's purpose and usage
      - `matchType` 'EXACT_MATCH', required
      - `settings` SettingReference[], required: Settings to apply with traffic distribution (percentages must sum to 100)
        - `settingId` string, required: Setting resource ID (TypeID format)
        - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `value` string, required: Exact URL to match. Must be unique - only one rule per value allowed. Example: 'https://api.example.com/webhooks/voice/incoming'
    - DefaultRule: Rule that matches all incoming requests not matched by other rules. Only ONE default rule allowed per account. Evaluated only when no exact-match or prefix-match rule matches.
      - `id` string, required: Unique Rule identifier (TypeID/TTID format)
      - `friendlyName` string: Human-readable name for identification
      - `description` string: Optional description of the Rule's purpose and usage
      - `matchType` 'DEFAULT', required
      - `settings` SettingReference[], required: Settings to apply with traffic distribution (percentages must sum to 100)
        - `settingId` string, required: Setting resource ID (TypeID format)
        - `percentage` integer, required: Percentage of traffic to route (all settings in rule must sum to 100)
      - `createdAt` string, date-time
      - `updatedAt` string, date-time

## Other responses

- `400`: Validation error (percentages not summing to 100, invalid fields)
- `401`: Authentication failed
- `403`: Authenticated account does not have permission to perform this operation
- `404`: Rule not found
- `409`: New match key collides with another Rule
- `422`: Referenced Setting not found or security guardrail violation
- `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)
