Track webhook rule changes

(new)

Public Beta

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 covers Public Beta products.

A Webhook Rule 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

Twilio validates your request. An invalid request returns 400, 409, or 422 and nothing changes.
A valid request returns 202 Accepted with three headers: Operation-Id, Location pointing at the Operation, and Retry-After.
The change propagates to every region, which typically takes 30 to 60 seconds.
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)

Behavior during propagation

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`	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.

1curl -X GET https://webhooks.twilio.com/v1/Webhooks/Operations/{OPERATION_ID} \
2     -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.

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

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

1curl -X GET 'https://webhooks.twilio.com/v1/Webhooks/Operations?status=RUNNING&resourceId={RULE_ID}' \
2     -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, the main reason to watch an Operation
Configuration API FAQs