---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/usage/webhooks/webhook-operations#article
headline: Track webhook rule changes
description: Poll the Operations resource to confirm that a Webhook Rule change has propagated to Twilio's webhook delivery plane.
url: https://www.twilio.com/docs/usage/webhooks/webhook-operations
inLanguage: en
dateModified: 2026-09-07T13:32:03.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Track webhook rule changes

> \[!IMPORTANT]
>
> The Webhooks configuration API, including the Webhook Settings and Webhook Rules resources, has been released as a Public Beta product. Before Twilio declares this product as Generally Available, the information contained in this document might change. Twilio might implement additional features or change others. No [Twilio SLA][sla] covers Public Beta products.

[sla]: https://help.twilio.com/articles/115002413087-Twilio-Beta-product-support

A [Webhook Rule][rules] write is saved immediately, but it doesn't take effect until it propagates to the plane that delivers your webhooks. An Operation tracks that propagation so you can confirm when the change is live.

Settings, AuthProfiles, and SharedKeys propagate on the same 30 to 60 second timescale, but they create no Operation. There's nothing to poll, so allow that window before relying on them.

## What happens when you change a rule

1. Twilio validates your request. An invalid request returns `400`, `409`, or `422` and nothing changes.
2. A valid request returns `202 Accepted` with three headers: `Operation-Id`, `Location` pointing at the Operation, and `Retry-After`.
3. The change propagates to every region, which typically takes **30 to 60 seconds**.
4. The Operation's status becomes `COMPLETED`.

The `202` response body carries the Operation and, for create and update, the Rule as it stood when Twilio accepted the change. Delete responses omit the Rule.

> \[!WARNING]
>
> Until the Operation completes, some webhooks may still use the previous configuration. A newly created Rule may not match yet, so its traffic can fall through to another Rule or to the default Rule. Don't remove the old Setting until the Operation reports `COMPLETED`.

## Operation properties

| Property          | Type   | Description                                                                       |
| ----------------- | ------ | --------------------------------------------------------------------------------- |
| `id`              | string | The Operation's identifier, in the form `webhooks_operation_` plus 26 characters. |
| `statusUrl`       | string | Where to poll for status. Matches the `Location` header on the `202` response.    |
| [`status`][st]    | enum   | The Operation's current state.                                                    |
| `resourceId`      | string | The Rule the Operation affects.                                                   |
| `error`           | object | Present only when `status` is `FAILED`.                                           |
| `createdAt`       | string | When Twilio accepted the change, as an ISO 8601 timestamp.                        |
| `completedAt`     | string | When the Operation finished, as an ISO 8601 timestamp.                            |
| `retentionPeriod` | string | How long Twilio keeps the record, as an ISO 8601 duration. Fixed at seven days.   |

## Status values

| `status`    | Meaning                                                      |
| ----------- | ------------------------------------------------------------ |
| `PENDING`   | Accepted, not yet started.                                   |
| `RUNNING`   | Propagating to all regions.                                  |
| `COMPLETED` | The change is active globally.                               |
| `CANCELLED` | The Operation stopped before completing.                     |
| `FAILED`    | The Operation couldn't complete. See `error` for the reason. |

When `status` is `FAILED`, `error` carries a `type` URI, a `title`, a numeric Twilio `code`, and a `detail` explaining this occurrence.

## Check an operation

Poll the `Operation-Id` you received from the Rule change.

```bash
curl -X GET https://webhooks.twilio.com/v1/Webhooks/Operations/{OPERATION_ID} \
     -u {API_KEY_SID}:{API_KEY_SECRET}
```

Respect the `Retry-After` header from the `202` response rather than polling tightly. Most Operations complete within a minute.

## Recover a lost operation ID

If your process lost the `Operation-Id` before persisting it, list your Operations. Results come back newest first.

```bash
curl -X GET https://webhooks.twilio.com/v1/Webhooks/Operations \
     -u {API_KEY_SID}:{API_KEY_SECRET}
```

Narrow the list by state or by the Rule it affects.

```bash
curl -X GET 'https://webhooks.twilio.com/v1/Webhooks/Operations?status=RUNNING&resourceId={RULE_ID}' \
     -u {API_KEY_SID}:{API_KEY_SECRET}
```

Operation records are retained for seven days from creation, so an Operation older than that no longer appears.

## What's next?

* [Shift traffic between settings][rules-traffic], the main reason to watch an Operation
* [Configuration API FAQs][faq]

[rules]: /docs/usage/webhooks/webhook-rules

[st]: #status-values

[rules-traffic]: /docs/usage/webhooks/webhook-rules#shift-traffic-between-settings

[faq]: /docs/usage/webhooks/webhook-configuration-faq