Draft: Workers event notifications

[yomna-shousha]

Draft reference page for Workers event notifications via Queues event subscriptions. Covers gradual deployment events, deployment/version lifecycle, routing, secrets/tags/settings, account-level events, and Workers for Platforms — with milestone 1 and milestone 2 breakdown.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/workers/	@cloudflare/workers-docs, @GregBrimble, @irvinebroque, @mikenomitch, @korinne, @WalshyDev, @cloudflare/deploy-config, @cloudflare/product-owners, @cloudflare/wrangler, @MattieTK, @cloudflare/dev-plat-leads, @vy-ton

[ask-bonk]

PR Review: Workers event notifications reference

Summary

This PR adds a new reference page (event-notifications.mdx) cataloging Workers lifecycle and configuration events available through Queues event subscriptions. The page is well-structured into event sources, Milestone 1 (gradual deployments, lifecycle, routing, secrets/settings, account-level, and Workers for Platforms), and Milestone 2 (granular settings). Links are valid and frontmatter is mostly complete.

Issues flagged — needs maintainer attention

1. Duplicate version.created event with conflicting semantics (lines 56 and 89)
The same event name and type field (cf.workers.worker.version.created) is used for two completely different concepts:

• Line 56: "A new version was explicitly uploaded (for example, wrangler versions upload)"
• Line 89: "A versioned setting was changed (bindings, limits, placement)"

This appears to be a copy-paste error. These should have distinct event names and type values so customers can differentiate them.

Suggested fix: Rename the settings-table entry to something like settings.versionedUpdated with a corresponding type of cf.workers.worker.settings.versionedUpdated (or whatever the actual product API uses).

2. Draft content in a Note admonition (lines 92–94)

:::note[Open question]
Secret changes create new versions under the hood. These events may collapse into `version.created` in a future revision — to be determined based on whether customers prefer granular secret-level events or version-level events.
:::

The :::note[Open question] framing signals that the product behavior is undecided. Published docs should not contain unresolved product deliberations. Please resolve this before merging — either remove the note, convert it to a standard :::note with settled guidance, or move the context to an internal doc.

Style / polish suggestions

3. Unused component import (line 14)
Render is imported but never used on the page. Remove the import:

- import { Render } from "~/components";

4. Redundant <title> tag in frontmatter (lines 7–9)
Starlight automatically generates the <title> tag from the title: field. The head: block is unnecessary here and can be removed:

- head:
-   - tag: title
-     content: Event notifications

5. Missing Oxford comma (line 90)
Per the style guide, use an Oxford comma in lists of three or more:

- | `settings.updated` | `cf.workers.worker.settings.updated` | An unversioned setting was changed (observability, logpush, tail consumers, subdomain) |
+ | `settings.updated` | `cf.workers.worker.settings.updated` | An unversioned setting was changed (observability, logpush, tail consumers, and subdomain) |

Labels

Applying content, workers, documentation.

[ask-bonk]

Done. Here's a summary of my review on PR #31826:

Labels applied

• content:new — this is a new reference page
• triage — flagged for docs team review
• product:workers was already present

Summary of the PR

This PR adds a new reference page (src/content/docs/workers/configuration/event-notifications.mdx) that catalogs Workers lifecycle and configuration events available through Queues event subscriptions. It's organized by event source (workers, workers.worker, workers.dispatchNamespace) and split into Milestone 1 (current events) and Milestone 2 (future granular settings events). Coverage includes gradual deployments, version/deployment lifecycle, routing, secrets/tags/settings, account-level events, and Workers for Platforms.

Issues flagged

Critical — needs maintainer attention before merge:

1. Duplicate/conflicting version.created event (lines 56 and 89) — The same event name and type field (cf.workers.worker.version.created) is used for two different concepts: "A new version was explicitly uploaded" vs. "A versioned setting was changed." This looks like a copy-paste error and needs distinct identifiers.

2. Draft content in a Note admonition (lines 92–94) — The :::note[Open question] block frames a product decision as unresolved. Published docs should not contain open product deliberations.

Style / polish:

3. Unused import — Render is imported but never used.
4. Redundant head: frontmatter — Starlight auto-generates <title> from title:; the head: block is unnecessary.
5. Missing Oxford comma in the settings description on line 90.

All of this has been posted as a review comment on PR #31826.

github run

[yomna-shousha]

this will not be merged in

[github-actions]

Preview URL: https://9e9c577f.preview.developers.cloudflare.com
Preview Branch URL: https://workers-notifs.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/configuration/event-notifications/	https://workers-notifs.preview.developers.cloudflare.com/workers/configuration/event-notifications/