---
title: "Delete Rule (hard delete, async)"
method: DELETE
path: "/v1/Webhooks/Rules/{ruleId}"
tags: ["Rules"]
---

# Delete Rule (hard delete, async)

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

## Request

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

Permanently deletes a Rule. Returns 202 Accepted; the deletion propagates globally in 30-60 seconds. Poll the returned Operation-Id for completion.

## Headers

- `Idempotency-Key` string, uuid

## Response `202`

Rule deletion 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

- `401`: Authentication failed
- `403`: Authenticated account does not have permission to perform this operation
- `404`: Rule not found
- `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)
