Event notifications

Event notifications send messages to your queue when data in your R2 bucket changes. You can consume these messages with a consumer Worker or pull over HTTP from outside of Cloudflare Workers.

Get started with event notifications

Prerequisites

Before getting started, you will need:

An existing R2 bucket. If you do not already have an existing R2 bucket, refer to Create buckets.
An existing queue. If you do not already have a queue, refer to Create a queue.
A consumer Worker or HTTP pull enabled on your Queue.

Enable event notifications via Dashboard

From the Cloudflare dashboard, select R2 from the sidebar.
Select the bucket you'd like to add an event notification rule to.
Switch to the Settings tab, then scroll down to the Event notifications card.
Select Add notification and choose the queue you'd like to receive notifications and the type of events that will trigger them.
Select Add notification.

Enable event notifications via Wrangler

Set up Wrangler

To begin, install npm ↗. Then install Wrangler, the Developer Platform CLI.

Enable event notifications on your R2 bucket

Log in to Wrangler with the wrangler login command. Then add an event notification rule to your bucket by running the r2 bucket notification create command.

npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME>

To add filtering based on prefix or suffix use the --prefix or --suffix flag, respectively.

# Filter using prefix
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>"

# Filter using suffix
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --suffix "<SUFFIX_VALUE>"

# Filter using prefix and suffix. Both the conditions will be used for filtering
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>" --suffix "<SUFFIX_VALUE>"

For a more complete step-by-step example, refer to the Log and store upload events in R2 with event notifications example.

Event notification rules

Event notification rules determine the event types that trigger notifications and optionally enable filtering based on object prefix and suffix. You can have up to 100 event notification rules per R2 bucket.

Event types

Event type	Description	Trigger actions
`object-create`	Triggered when new objects are created or existing objects are overwritten.	`PutObject` `CopyObject` `CompleteMultipartUpload`
`object-delete`	Triggered when an object is explicitly removed from the bucket.	`DeleteObject` `LifecycleDeletion`

Message format

Queue consumers receive notifications as Messages. The following is an example of the body of a message that a consumer Worker will receive:

{
  "account": "3f4b7e3dcab231cbfdaa90a6a28bd548",
  "action": "CopyObject",
  "bucket": "my-bucket",
  "object": {
    "key": "my-new-object",
    "size": 65536,
    "eTag": "c846ff7a18f28c2e262116d6e8719ef0"
  },
  "eventTime": "2024-05-24T19:36:44.379Z",
  "copySource": {
    "bucket": "my-bucket",
    "object": "my-original-object"
  }
}

Properties

Property	Type	Description
`account`	String	The Cloudflare account ID that the event is associated with.
`action`	String	The type of action that triggered the event notification. Example actions include: `PutObject`, `CopyObject`, `CompleteMultipartUpload`, `DeleteObject`.
`bucket`	String	The name of the bucket where the event occurred.
`object`	Object	A nested object containing details about the object involved in the event.
`object.key`	String	The key (or name) of the object within the bucket.
`object.size`	Number	The size of the object in bytes. Note: not present for object-delete events.
`object.eTag`	String	The entity tag (eTag) of the object. Note: not present for object-delete events.
`eventTime`	String	The time when the action that triggered the event occurred.
`copySource`	Object	A nested object containing details about the source of a copied object. Note: only present for events triggered by `CopyObject`.
`copySource.bucket`	String	The bucket that contained the source object.
`copySource.object`	String	The name of the source object.

Notes

Queues per-queue message throughput is currently 5,000 messages per second. If your workload produces more than 5,000 notifications per second, we recommend splitting notification rules across multiple queues.

Was this helpful?

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings