diff --git a/public/images/queues/queues-event-subscriptions.png b/public/images/queues/queues-event-subscriptions.png new file mode 100644 index 00000000000000..f00d85611323c7 Binary files /dev/null and b/public/images/queues/queues-event-subscriptions.png differ diff --git a/src/assets/images/queues/queues-event-subscriptions.png b/src/assets/images/queues/queues-event-subscriptions.png new file mode 100644 index 00000000000000..f00d85611323c7 Binary files /dev/null and b/src/assets/images/queues/queues-event-subscriptions.png differ diff --git a/src/content/changelog/queues/2025-08-19-event-subscriptions.mdx b/src/content/changelog/queues/2025-08-19-event-subscriptions.mdx new file mode 100644 index 00000000000000..db4db43ffc7866 --- /dev/null +++ b/src/content/changelog/queues/2025-08-19-event-subscriptions.mdx @@ -0,0 +1,42 @@ +--- +title: Subscribe to events from Cloudflare services with Queues +description: Subscribe to events from Cloudflare services to build custom workflows, integrations, and logic. +products: + - queues +date: 2025-08-19 12:00:00 UTC +--- + +You can now subscribe to events from other Cloudflare services (for example, [Workers KV](/kv/), [Workers AI](/workers-ai), [Workers](/workers)) and consume those events via [Queues](/queues/), allowing you to build custom workflows, integrations, and logic in response to account activity. + +![Event subscriptions architecture](~/assets/images/queues/queues-event-subscriptions.png) + +Event subscriptions allow you to receive messages when events occur across your Cloudflare account. Cloudflare products can publish structured events to a queue, which you can then consume with [Workers](/workers/) or [pull via HTTP from anywhere](/queues/configuration/pull-consumers/). + +To create a subscription, use the dashboard or [Wrangler](/workers/wrangler/commands/#subscription-create): + +```bash +npx wrangler queues subscription create my-queue --source r2 --events bucket.created +``` + +An event is a structured record of something happening in your Cloudflare account – like a Workers AI batch request being queued, a Worker build completing, or an R2 bucket being created. Events follow a consistent structure: + +```json title="Example R2 bucket created event" +{ + "type": "cf.r2.bucket.created", + "source": { + "type": "r2" + }, + "payload": { + "name": "my-bucket", + "location": "WNAM" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventTimestamp": "2025-07-28T10:30:00Z" + } +} +``` + +Current [event sources](/queues/event-subscriptions/events-schemas/) include [R2](/r2/), [Workers KV](/kv/), [Workers AI](/workers-ai/), [Workers Builds](/workers/ci-cd/builds/), [Vectorize](/vectorize/), [Super Slurper](/r2/data-migration/super-slurper/), and [Workflows](/workflows/). More sources and events are on the way. + +For more information on event subscriptions, available events, and how to get started, refer to our [documentation](/queues/event-subscriptions/). \ No newline at end of file diff --git a/src/content/docs/queues/event-subscriptions/events-schemas.mdx b/src/content/docs/queues/event-subscriptions/events-schemas.mdx new file mode 100644 index 00000000000000..bd932b413f3469 --- /dev/null +++ b/src/content/docs/queues/event-subscriptions/events-schemas.mdx @@ -0,0 +1,769 @@ +--- +title: Events & schemas +pcx_content_type: reference +sidebar: + order: 2 +head: + - tag: title + content: Events & schemas +--- + +This page provides a comprehensive reference of available event sources and their corresponding events with schemas for [event subscriptions](/queues/event-subscriptions/). All events include common metadata fields and follow a consistent structure. + +## Sources + +### R2 + +#### `bucket.created` + +Triggered when a bucket is created. + +**Example:** + +```json +{ + "type": "cf.r2.bucket.created", + "source": { + "type": "r2" + }, + "payload": { + "name": "my-bucket", + "jurisdiction": "default", + "location": "WNAM", + "storageClass": "Standard" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `bucket.deleted` + +Triggered when a bucket is deleted. + +**Example:** + +```json +{ + "type": "cf.r2.bucket.deleted", + "source": { + "type": "r2" + }, + "payload": { + "name": "my-bucket", + "jurisdiction": "default" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +### Super Slurper + +#### `job.started` + +Triggered when a migration job starts. + +**Example:** + +```json +{ + "type": "cf.superSlurper.job.started", + "source": { + "type": "superSlurper" + }, + "payload": { + "id": "job-12345678-90ab-cdef-1234-567890abcdef", + "createdAt": "2025-05-01T02:48:57.132Z", + "overwrite": true, + "pathPrefix": "migrations/", + "source": { + "provider": "s3", + "bucket": "source-bucket", + "region": "us-east-1", + "endpoint": "s3.amazonaws.com" + }, + "destination": { + "provider": "r2", + "bucket": "destination-bucket", + "jurisdiction": "default" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `job.paused` + +Triggered when a migration job pauses. + +**Example:** + +```json +{ + "type": "cf.superSlurper.job.paused", + "source": { + "type": "superSlurper" + }, + "payload": { + "id": "job-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `job.resumed` + +Triggered when a migration job resumes. + +**Example:** + +```json +{ + "type": "cf.superSlurper.job.resumed", + "source": { + "type": "superSlurper" + }, + "payload": { + "id": "job-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `job.completed` + +Triggered when a migration job finishes. + +**Example:** + +```json +{ + "type": "cf.superSlurper.job.completed", + "source": { + "type": "superSlurper" + }, + "payload": { + "id": "job-12345678-90ab-cdef-1234-567890abcdef", + "totalObjectsCount": 1000, + "skippedObjectsCount": 10, + "migratedObjectsCount": 980, + "failedObjectsCount": 10 + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `job.aborted` + +Triggered when a migration job is manually aborted. + +**Example:** + +```json +{ + "type": "cf.superSlurper.job.aborted", + "source": { + "type": "superSlurper" + }, + "payload": { + "id": "job-12345678-90ab-cdef-1234-567890abcdef", + "totalObjectsCount": 1000, + "skippedObjectsCount": 100, + "migratedObjectsCount": 500, + "failedObjectsCount": 50 + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +**Example:** + +```json +{ + "type": "cf.superSlurper.job.object.migrated", + "source": { + "type": "superSlurper.job", + "jobId": "job-12345678-90ab-cdef-1234-567890abcdef" + }, + "payload": { + "key": "migrations/file.txt" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +### Vectorize + +#### `index.created` + +Triggered when an index is created. + +**Example:** + +```json +{ + "type": "cf.vectorize.index.created", + "source": { + "type": "vectorize" + }, + "payload": { + "name": "my-vector-index", + "description": "Index for embeddings", + "createdAt": "2025-05-01T02:48:57.132Z", + "modifiedAt": "2025-05-01T02:48:57.132Z", + "dimensions": 1536, + "metric": "cosine" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `index.deleted` + +Triggered when an index is deleted. + +**Example:** + +```json +{ + "type": "cf.vectorize.index.deleted", + "source": { + "type": "vectorize" + }, + "payload": { + "name": "my-vector-index" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +### Workers AI + +#### `batch.queued` + +Triggered when a batch request is queued. + +**Example:** + +```json +{ + "type": "cf.workersAi.model.batch.queued", + "source": { + "type": "workersAi.model", + "modelName": "@cf/baai/bge-base-en-v1.5" + }, + "payload": { + "requestId": "req-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `batch.succeeded` + +Triggered when a batch request has completed. + +**Example:** + +```json +{ + "type": "cf.workersAi.model.batch.succeeded", + "source": { + "type": "workersAi.model", + "modelName": "@cf/baai/bge-base-en-v1.5" + }, + "payload": { + "requestId": "req-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `batch.failed` + +Triggered when a batch request has failed. + +**Example:** + +```json +{ + "type": "cf.workersAi.model.batch.failed", + "source": { + "type": "workersAi.model", + "modelName": "@cf/baai/bge-base-en-v1.5" + }, + "payload": { + "requestId": "req-12345678-90ab-cdef-1234-567890abcdef", + "message": "Model execution failed", + "internalCode": 5001, + "httpCode": 500 + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +### Workers Builds + +#### `build.started` + +Triggered when a build starts. + +**Example:** + +```json +{ + "type": "cf.workersBuilds.worker.build.started", + "source": { + "type": "workersBuilds.worker", + "workerName": "my-worker" + }, + "payload": { + "buildUuid": "build-12345678-90ab-cdef-1234-567890abcdef", + "status": "running", + "buildOutcome": null, + "createdAt": "2025-05-01T02:48:57.132Z", + "initializingAt": "2025-05-01T02:48:58.132Z", + "runningAt": "2025-05-01T02:48:59.132Z", + "stoppedAt": null, + "buildTriggerMetadata": { + "buildTriggerSource": "push_event", + "branch": "main", + "commitHash": "abc123def456", + "commitMessage": "Fix bug in authentication", + "author": "developer@example.com", + "buildCommand": "npm run build", + "deployCommand": "wrangler deploy", + "rootDirectory": "/", + "repoName": "my-worker-repo", + "providerAccountName": "github-user", + "providerType": "github" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `build.failed` + +Triggered when a build fails. + +**Example:** + +```json +{ + "type": "cf.workersBuilds.worker.build.failed", + "source": { + "type": "workersBuilds.worker", + "workerName": "my-worker" + }, + "payload": { + "buildUuid": "build-12345678-90ab-cdef-1234-567890abcdef", + "status": "failed", + "buildOutcome": "failure", + "createdAt": "2025-05-01T02:48:57.132Z", + "initializingAt": "2025-05-01T02:48:58.132Z", + "runningAt": "2025-05-01T02:48:59.132Z", + "stoppedAt": "2025-05-01T02:50:00.132Z", + "buildTriggerMetadata": { + "buildTriggerSource": "push_event", + "branch": "main", + "commitHash": "abc123def456", + "commitMessage": "Fix bug in authentication", + "author": "developer@example.com", + "buildCommand": "npm run build", + "deployCommand": "wrangler deploy", + "rootDirectory": "/", + "repoName": "my-worker-repo", + "providerAccountName": "github-user", + "providerType": "github" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `build.canceled` + +Triggered when a build is canceled. + +**Example:** + +```json +{ + "type": "cf.workersBuilds.worker.build.canceled", + "source": { + "type": "workersBuilds.worker", + "workerName": "my-worker" + }, + "payload": { + "buildUuid": "build-12345678-90ab-cdef-1234-567890abcdef", + "status": "canceled", + "buildOutcome": "canceled", + "createdAt": "2025-05-01T02:48:57.132Z", + "initializingAt": "2025-05-01T02:48:58.132Z", + "runningAt": "2025-05-01T02:48:59.132Z", + "stoppedAt": "2025-05-01T02:49:30.132Z", + "buildTriggerMetadata": { + "buildTriggerSource": "push_event", + "branch": "main", + "commitHash": "abc123def456", + "commitMessage": "Fix bug in authentication", + "author": "developer@example.com", + "buildCommand": "npm run build", + "deployCommand": "wrangler deploy", + "rootDirectory": "/", + "repoName": "my-worker-repo", + "providerAccountName": "github-user", + "providerType": "github" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `build.succeeded` + +Triggered when a build succeeds. + +**Example:** + +```json +{ + "type": "cf.workersBuilds.worker.build.succeeded", + "source": { + "type": "workersBuilds.worker", + "workerName": "my-worker" + }, + "payload": { + "buildUuid": "build-12345678-90ab-cdef-1234-567890abcdef", + "status": "success", + "buildOutcome": "success", + "createdAt": "2025-05-01T02:48:57.132Z", + "initializingAt": "2025-05-01T02:48:58.132Z", + "runningAt": "2025-05-01T02:48:59.132Z", + "stoppedAt": "2025-05-01T02:50:15.132Z", + "buildTriggerMetadata": { + "buildTriggerSource": "push_event", + "branch": "main", + "commitHash": "abc123def456", + "commitMessage": "Fix bug in authentication", + "author": "developer@example.com", + "buildCommand": "npm run build", + "deployCommand": "wrangler deploy", + "rootDirectory": "/", + "repoName": "my-worker-repo", + "providerAccountName": "github-user", + "providerType": "github" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +### Workers KV + +#### `namespace.created` + +Triggered when a namespace is created. + +**Example:** + +```json +{ + "type": "cf.kv.namespace.created", + "source": { + "type": "kv" + }, + "payload": { + "id": "ns-12345678-90ab-cdef-1234-567890abcdef", + "name": "my-kv-namespace" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `namespace.deleted` + +Triggered when a namespace is deleted. + +**Example:** + +```json +{ + "type": "cf.kv.namespace.deleted", + "source": { + "type": "kv" + }, + "payload": { + "id": "ns-12345678-90ab-cdef-1234-567890abcdef", + "name": "my-kv-namespace" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +### Workflows + +#### `instance.queued` + +Triggered when an instance was created and is awaiting execution. + +**Example:** + +```json +{ + "type": "cf.workflows.workflow.instance.queued", + "source": { + "type": "workflows.workflow", + "workflowName": "my-workflow" + }, + "payload": { + "versionId": "v1", + "instanceId": "inst-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `instance.started` + +Triggered when an instance starts or resumes execution. + +**Example:** + +```json +{ + "type": "cf.workflows.workflow.instance.started", + "source": { + "type": "workflows.workflow", + "workflowName": "my-workflow" + }, + "payload": { + "versionId": "v1", + "instanceId": "inst-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `instance.paused` + +Triggered when an instance pauses execution. + +**Example:** + +```json +{ + "type": "cf.workflows.workflow.instance.paused", + "source": { + "type": "workflows.workflow", + "workflowName": "my-workflow" + }, + "payload": { + "versionId": "v1", + "instanceId": "inst-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `instance.errored` + +Triggered when an instance step throws an error. + +**Example:** + +```json +{ + "type": "cf.workflows.workflow.instance.errored", + "source": { + "type": "workflows.workflow", + "workflowName": "my-workflow" + }, + "payload": { + "versionId": "v1", + "instanceId": "inst-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `instance.terminated` + +Triggered when an instance is manually terminated. + +**Example:** + +```json +{ + "type": "cf.workflows.workflow.instance.terminated", + "source": { + "type": "workflows.workflow", + "workflowName": "my-workflow" + }, + "payload": { + "versionId": "v1", + "instanceId": "inst-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +#### `instance.completed` + +Triggered when an instance finishes execution successfully. + +**Example:** + +```json +{ + "type": "cf.workflows.workflow.instance.completed", + "source": { + "type": "workflows.workflow", + "workflowName": "my-workflow" + }, + "payload": { + "versionId": "v1", + "instanceId": "inst-12345678-90ab-cdef-1234-567890abcdef" + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2025-05-01T02:48:57.132Z" + } +} +``` + +## Common schema fields + +All events include these common fields: + +| Field | Type | Description | +|-------|------|-------------| +| `type` | string | The event type identifier | +| `source` | object | Contains source-specific information like IDs and names | +| `metadata.accountId` | string | Your Cloudflare account ID | +| `metadata.eventSubscriptionId` | string | The subscription that triggered this event | +| `metadata.eventSchemaVersion` | number | The version of the event schema | +| `metadata.eventTimestamp` | string | The ISO 8601 timestamp when the event occurred | +| `payload` | object | The event-specific data containing details about what happened | \ No newline at end of file diff --git a/src/content/docs/queues/event-subscriptions/index.mdx b/src/content/docs/queues/event-subscriptions/index.mdx new file mode 100644 index 00000000000000..b2fddd2545146a --- /dev/null +++ b/src/content/docs/queues/event-subscriptions/index.mdx @@ -0,0 +1,34 @@ +--- +title: Event subscriptions +pcx_content_type: overview +sidebar: + order: 4 +head: + - tag: title + content: Event subscriptions overview +description: Subscribe to events from Cloudflare services to build custom workflows, integrations, and logic with Workers. +--- + +import { LinkCard } from "~/components" + +Event subscriptions allow you to receive messages when events occur across your Cloudflare account. Cloudflare products (e.g., [KV](/kv/), [Workers AI](/workers-ai), [Workers](/workers)) can publish structured events to a queue, which you can then consume with Workers or [HTTP pull consumers](/queues/configuration/pull-consumers/) to build custom workflows, integrations, or logic. + +![Event subscriptions architecture](public/images/queues/queues-event-subscriptions.png) + +## What is an event? + +An event is a structured record of something happening in your Cloudflare account – like a Workers AI batch request being queued, a Worker build completing, or an R2 bucket being created. When you subscribe to these events, your queue will automatically start receiving messages when the events occur. + +## Learn more + + + + \ No newline at end of file diff --git a/src/content/docs/queues/event-subscriptions/manage-event-subscriptions.mdx b/src/content/docs/queues/event-subscriptions/manage-event-subscriptions.mdx new file mode 100644 index 00000000000000..7c971fce852d62 --- /dev/null +++ b/src/content/docs/queues/event-subscriptions/manage-event-subscriptions.mdx @@ -0,0 +1,93 @@ +--- +pcx_content_type: configuration +title: Manage event subscriptions +description: Learn how to create, view, and delete event subscriptions for your queues. +sidebar: + order: 1 +--- + +import { + Steps, + LinkCard, +} from "~/components"; + +Learn how to: + +- Create event subscriptions to receive messages from Cloudflare services. +- View existing subscriptions on your queues. +- Delete subscriptions you no longer need. + +## Create subscription + +Creating a subscription allows your queue to receive messages when events occur in Cloudflare services. You can specify which source and events you want to subscribe to. + +### Dashboard + + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and go to **Compute & AI** > **Queues**. +2. Select the queue you want to add a subscription to. +3. Switch to the **Subscriptions** tab. +4. Select **Subscribe to events**. +5. Name your subscription, and select the desired source and events. +6. Select **Subscribe**. + + +### Wrangler CLI + +To create a subscription using Wrangler, run the [`queues subscription create command`](/queues/reference/wrangler-commands/#queues-subscription-create): + +```bash +npx wrangler queues subscription create --source --events -- +``` + +To learn more about which sources and events you can subscribe to, refer to [Events & schemas](/queues/event-subscriptions/events-schemas/). + +## View existing subscriptions + +You can view all subscriptions configured for a queue to see what events it is currently receiving. + +### Dashboard + + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and go to **Compute & AI** > **Queues**. +2. Select the queue you want to view subscriptions for. +3. Switch to the **Subscriptions** tab. + + +### Wrangler CLI + +To list subscriptions for a queue, run the [`queues subscription list command`](/queues/reference/wrangler-commands/#queues-subscription-list): + +```bash +npx wrangler queues subscription list +``` + +## Delete subscription + +When you delete a subscription, your queue will stop receiving messages for those events immediately. + +### Dashboard + + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and go to **Compute & AI** > **Queues**. +2. Select the queue containing the subscription you want to delete. +3. Switch to the **Subscriptions** tab. +4. Select **...** for the subscription you want to delete. +5. Select **Delete subscription**. + + +### Wrangler CLI + +To delete a subscription, run the [`queues subscription delete command`](/queues/reference/wrangler-commands/#queues-subscription-delete): + +```bash +npx wrangler queues subscription delete --id +``` + +## Learn more + + \ No newline at end of file diff --git a/src/content/docs/queues/index.mdx b/src/content/docs/queues/index.mdx index 89088438f2aa9d..4815f11c65837a 100644 --- a/src/content/docs/queues/index.mdx +++ b/src/content/docs/queues/index.mdx @@ -9,7 +9,7 @@ head: content: Overview --- -import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct } from "~/components" +import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, LinkButton } from "~/components" @@ -23,6 +23,8 @@ Send and receive messages with guaranteed delivery and no charges for egress ban Cloudflare Queues integrate with [Cloudflare Workers](/workers/) and enable you to build applications that can [guarantee delivery](/queues/reference/delivery-guarantees/), [offload work from a request](/queues/reference/how-queues-works/), [send data from Worker to Worker](/queues/configuration/configure-queues/), and [buffer or batch data](/queues/configuration/batching-retries/). +Get started + *** ## Features @@ -100,4 +102,8 @@ Learn how to configure Cloudflare Queues using Wrangler. Learn how to use JavaScript APIs to send and receive messages to a Cloudflare Queue. + +Learn how to configure and manage event subscriptions for your queues. + + diff --git a/src/content/docs/queues/reference/wrangler-commands.mdx b/src/content/docs/queues/reference/wrangler-commands.mdx index f849e4bd0f63c4..2a0357d42cf4de 100644 --- a/src/content/docs/queues/reference/wrangler-commands.mdx +++ b/src/content/docs/queues/reference/wrangler-commands.mdx @@ -1,8 +1,13 @@ --- pcx_content_type: navigation title: Wrangler commands -external_link: /workers/wrangler/commands/#queues sidebar: order: 30 --- + +import { Render } from "~/components"; + +Queues Wrangler commands use REST APIs to interact with the control plane. This page lists the Wrangler commands for Queues. + + diff --git a/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx b/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx index e047849bd44894..8cdc8b09f909d3 100644 --- a/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx +++ b/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx @@ -157,7 +157,7 @@ curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker- The dictionary can contain multiple key-value pairs. Each key indicates the name of the Worker the override should be applied to. The value indicates the version ID that should be used and must be a [String](https://www.rfc-editor.org/rfc/rfc8941#name-strings). -A version override will only be applied if the specified version is in the current deployment. The versions in the current deployment can be found using the [`wrangler deployments list`](/workers/wrangler/commands/#list-6) command or on the [Workers Dashboard](https://dash.cloudflare.com/?to=/:account/workers) under Worker > Deployments > Active Deployment. +A version override will only be applied if the specified version is in the current deployment. The versions in the current deployment can be found using the [`wrangler deployments list`](/workers/wrangler/commands/#list-5) command or on the [Workers Dashboard](https://dash.cloudflare.com/?to=/:account/workers) under Worker > Deployments > Active Deployment. :::note[Verifying that the version override was applied] diff --git a/src/content/docs/workers/configuration/versions-and-deployments/index.mdx b/src/content/docs/workers/configuration/versions-and-deployments/index.mdx index b2c8f308513261..686d29ad56a3cf 100644 --- a/src/content/docs/workers/configuration/versions-and-deployments/index.mdx +++ b/src/content/docs/workers/configuration/versions-and-deployments/index.mdx @@ -73,7 +73,7 @@ New versions are not created when you make changes to [resources connected to yo #### Via Wrangler -Wrangler allows you to view the 10 most recent versions and deployments. Refer to the [`versions list`](/workers/wrangler/commands/#list-5) and [`deployments`](/workers/wrangler/commands/#list-6) documentation to view the commands. +Wrangler allows you to view the 10 most recent versions and deployments. Refer to the [`versions list`](/workers/wrangler/commands/#list-4) and [`deployments`](/workers/wrangler/commands/#list-5) documentation to view the commands. #### Via the Cloudflare dashboard diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index 954136408260a1..dc2337edbe617f 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -1208,154 +1208,13 @@ Manage your [Pipelines](/pipelines/). +--- + ## `queues` Manage your Workers [Queues](/queues/) configurations. -### `create` - -Create a new queue. - -```txt -wrangler queues create [OPTIONS] -``` - -- `name` - - The name of the queue to create. -- `--delivery-delay-secs` - - How long a published message should be delayed for, in seconds. Must be a positive integer. -- `--message-retention-period-secs` - - How long a published message is retained in the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days). - - - -### `update` - -Update an existing queue. - -```txt -wrangler queues update [OPTIONS] -``` - -- `name` - - The name of the queue to update. -- `--delivery-delay-secs` - - How long a published message should be delayed for, in seconds. Must be a positive integer. -- `--message-retention-period-secs` - - How long a published message is retained on the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days). - - - -### `delete` - -Delete an existing queue. - -```txt -wrangler queues delete [OPTIONS] -``` - -- `name` - - The name of the queue to delete. - - - -### `list` - -List all queues in the current account. - -```txt -wrangler queues list [OPTIONS] -``` - - - -### `info` - -Get information on individual queues. - -```txt -wrangler queues info -``` - -- `name` - - The name of the queue to inspect. - -### `consumer` - -Manage queue consumer configurations. - -### `consumer add ` - -Add a Worker script as a [queue consumer](/queues/reference/how-queues-works/#consumers). - -```txt -wrangler queues consumer add [OPTIONS] -``` - -- `queue-name` - - The name of the queue to add the consumer to. -- `script-name` - - The name of the Workers script to add as a consumer of the named queue. -- `--batch-size` - - Maximum number of messages per batch. Must be a positive integer. -- `--batch-timeout` - - Maximum number of seconds to wait to fill a batch with messages. Must be a positive integer. -- `--message-retries` - - Maximum number of retries for each message. Must be a positive integer. -- `--max-concurrency` - - The maximum number of concurrent consumer invocations that will be scaled up to handle incoming message volume. Must be a positive integer. -- `--retry-delay-secs` - - How long a retried message should be delayed for, in seconds. Must be a positive integer. - - - -### `consumer remove` - -Remove a consumer from a queue. - -```txt -wrangler queues consumer remove -``` - -- `queue-name` - - The name of the queue to remove the consumer from. -- `script-name` - - The name of the Workers script to remove as the consumer. - - - -### `purge` - -Permanently delete all messages in a queue. - -```txt -wrangler queues purge -``` - -- `queue-name` - - The name of the queue from which messages should be deleted. - -### `pause-delivery` - -Pause message delivery from a Queue to consumers (including push consumers, and HTTP pull consumers) - -```txt -wrangler queues pause-delivery -``` - -- `queue-name` - - The name of the queue which delivery should be paused. - -### `resume-delivery` - -Resume delivery from a Queue to consumers (including push consumers, and HTTP pull consumers) - -```txt -wrangler queues resume-delivery -``` - -- `queue-name` - - The name of the queue from which delivery should be resumed. + --- diff --git a/src/content/partials/workers/wrangler-commands/queues.mdx b/src/content/partials/workers/wrangler-commands/queues.mdx new file mode 100644 index 00000000000000..f9281f8d354dd8 --- /dev/null +++ b/src/content/partials/workers/wrangler-commands/queues.mdx @@ -0,0 +1,248 @@ +--- +{} +--- + +import { Render, AnchorHeading, Type, MetaInfo } from "~/components"; + + + +Create a new queue. + +```txt +wrangler queues create [OPTIONS] +``` + +- `name` + - The name of the queue to create. +- `--delivery-delay-secs` + - How long a published message should be delayed for, in seconds. Must be a positive integer. +- `--message-retention-period-secs` + - How long a published message is retained in the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days). + + + + + +Update an existing queue. + +```txt +wrangler queues update [OPTIONS] +``` + +- `name` + - The name of the queue to update. +- `--delivery-delay-secs` + - How long a published message should be delayed for, in seconds. Must be a positive integer. +- `--message-retention-period-secs` + - How long a published message is retained on the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days). + + + + + +Delete an existing queue. + +```txt +wrangler queues delete [OPTIONS] +``` + +- `name` + - The name of the queue to delete. + + + + + +List all queues in the current account. + +```txt +wrangler queues list [OPTIONS] +``` + + + + + +Get information on individual queues. + +```txt +wrangler queues info +``` + +- `name` + - The name of the queue to inspect. + + + +Manage queue consumer configurations. + + + +Add a Worker script as a [queue consumer](/queues/reference/how-queues-works/#consumers). + +```txt +wrangler queues consumer add [OPTIONS] +``` + +- `queue-name` + - The name of the queue to add the consumer to. +- `script-name` + - The name of the Workers script to add as a consumer of the named queue. +- `--batch-size` + - Maximum number of messages per batch. Must be a positive integer. +- `--batch-timeout` + - Maximum number of seconds to wait to fill a batch with messages. Must be a positive integer. +- `--message-retries` + - Maximum number of retries for each message. Must be a positive integer. +- `--max-concurrency` + - The maximum number of concurrent consumer invocations that will be scaled up to handle incoming message volume. Must be a positive integer. +- `--retry-delay-secs` + - How long a retried message should be delayed for, in seconds. Must be a positive integer. + + + + + +Remove a consumer from a queue. + +```txt +wrangler queues consumer remove +``` + +- `queue-name` + - The name of the queue to remove the consumer from. +- `script-name` + - The name of the Workers script to remove as the consumer. + + + + + +Permanently delete all messages in a queue. + +```txt +wrangler queues purge +``` + +- `queue-name` + - The name of the queue from which messages should be deleted. + + + +Pause message delivery from a Queue to consumers (including push consumers, and HTTP pull consumers) + +```txt +wrangler queues pause-delivery +``` + +- `queue-name` + - The name of the queue which delivery should be paused. + + + +Resume delivery from a Queue to consumers (including push consumers, and HTTP pull consumers) + +```txt +wrangler queues resume-delivery +``` + +- `queue-name` + - The name of the queue from which delivery should be resumed. + + + +Create a new [event subscription](/queues/event-subscriptions/) for a queue. + +```txt +wrangler queues subscription create [OPTIONS] +``` + +- `queue-name` + - The name of the queue to create the subscription for. +- `--source` + - The event source type. Supported sources: `kv`, `r2`, `superSlurper`, `vectorize`, `workersAi.model`, `workersBuilds.worker`, `workflows.workflow`. +- `--events` + - Comma-separated list of event types to subscribe to. Refer to [Events & schemas](/queues/event-subscriptions/events-schemas/) for a complete list of all supported events. +- `--name` + - Name for the subscription. Auto-generated if not provided. +- `--enabled` + - Whether the subscription should be active. Defaults to true. +- Additional source-specific options (e.g., `--worker-name` for workersBuilds.worker, `--bucket-name` for r2.bucket). + + + + + +List all [event subscriptions](/queues/event-subscriptions/) for a queue. + +```txt +wrangler queues subscription list [OPTIONS] +``` + +- `queue-name` + - The name of the queue to list subscriptions for. +- `--page` + - Show a specific page from the listing. You can configure page size using "per-page". +- `--per-page` + - Configure the maximum number of subscriptions to show per page. +- `--json` + - Output in JSON format. + + + + + +Get details about a specific [event subscription](/queues/event-subscriptions/). + +```txt +wrangler queues subscription get [OPTIONS] +``` + +- `queue-name` + - The name of the queue. +- `--id` + - The ID of the subscription to retrieve. +- `--json` + - Output in JSON format. + + + + + +Update an existing [event subscription](/queues/event-subscriptions/). + +```txt +wrangler queues subscription update [OPTIONS] +``` + +- `queue-name` + - The name of the queue. +- `--id` + - The ID of the subscription to update. +- `--name` + - New name for the subscription. +- `--events` + - Comma-separated list of event types to subscribe to. +- `--enabled` + - Whether the subscription should be active. +- `--json` + - Output in JSON format. + + + + + +Delete an [event subscription](/queues/event-subscriptions/). + +```txt +wrangler queues subscription delete [OPTIONS] +``` + +- `queue-name` + - The name of the queue. +- `--id` + - The ID of the subscription to delete. +- `--force` + - Skip confirmation prompt. + + \ No newline at end of file