---
title: "Create a new Rule (async)"
method: POST
path: "/v1/Webhooks/Rules"
tags: ["Rules"]
---

# Create a new Rule (async)

`POST /v1/Webhooks/Rules`

## Request

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

Creates a URL matching rule. Returns immediately after validation, then propagates globally.

### How It Works

**Immediate:**
Request validated → 202 Accepted (with `Operation-Id` header) or 4xx error

**Async (30-60s):**
Propagates globally. Poll `/Operations/{id}` for status (`pending` → `completed`)

### During Propagation

During propagation, matching webhooks may use other rules (e.g., default) until this rule is active.

### Security Restrictions

Default rules (matchType: default) cannot use Basic Authentication. Use OAuth2, Digest, or create specific URL patterns instead.

## Headers

- `Idempotency-Key` string, uuid

## Request body

- union: Request body for creating a new Rule. Uses discriminator on matchType - each type has different required fields.
  - PostPrefixMatchRule
    - `friendlyName` string, nullable: Human-readable name for the Rule (optional, defaults to blank)
    - `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)
    - `prefix` string, required: URL prefix to match, MUST be unique across all prefix match rules and MUST end with `/`.
  - PostExactMatchRule
    - `friendlyName` string, nullable: Human-readable name for the Rule (optional, defaults to blank)
    - `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)
    - `value` string, required: Exact URL to match, MUST be unique across all exact match rules and MUST NOT end with `/`.
  - PostDefaultRule: Default rule - matches all incoming requests, no additional fields required, there can only be one default rule per account.
    - `friendlyName` string, nullable: Human-readable name for the Rule (optional, defaults to blank)
    - `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)

## Response `202`

Rule creation 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 (missing required fields, wildcard in pattern, percentages not summing to 100)
- `401`: Authentication failed
- `403`: Authenticated account does not have permission to perform this operation
- `409`: Rule with same match key already exists
- `422`: Referenced Setting not found, security guardrail violation, or account limit reached
- `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)
