Cloudflare Docs
R2
Edit this page
Report an issue with this page
Log into the Cloudflare dashboard
Set theme to dark (⇧+D)

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:

​​ Set up Wrangler

To begin, refer to Install/Update Wrangler to install Wrangler, the Cloudflare Developer Platform CLI. Log into Wrangler with the wrangler login command.

​​ Enable event notifications on your R2 bucket

To enable event notifications, add an event notification rule to your bucket by running the r2 bucket notification create command. Event notification rules determine the event types that trigger notifications and enable filtering based on object prefix and suffix.

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

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

​​ Event types

Event typeDescriptionTrigger actions
object-createTriggered when new objects are created or existing objects are overwritten.
  • PutObject
  • CopyObject
  • CompleteMultipartUpload
object-deleteTriggered when an object is explicitly removed from the bucket.

Note: During the beta, deletes that occur as a result of object lifecycle policies will not trigger this event.
  • DeleteObject

​​ 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

PropertyTypeDescription
accountStringThe Cloudflare account ID that the event is associated with.
actionStringThe type of action that triggered the event notification. Example actions include: PutObject, CopyObject, CompleteMultipartUpload, DeleteObject.
bucketStringThe name of the bucket where the event occurred.
objectObjectA nested object containing details about the object involved in the event.
object.keyStringThe key (or name) of the object within the bucket.
object.sizeNumberThe size of the object in bytes. Note: not present for object-delete events.
object.eTagStringThe entity tag (eTag) of the object. Note: not present for object-delete events.
eventTimeStringThe time when the action that triggered the event occurred.
copySourceObjectA nested object containing details about the source of a copied object. Note: only present for events triggered by CopyObject.
copySource.bucketStringThe bucket that contained the source object.
copySource.objectStringThe name of the source object.

​​ Limitations

During the beta, event notifications has the following limitations:

  • Queues per-queue message throughput is currently 400 messages per second. If your workload produces more than 400 notifications per second, messages may be dropped.
  • For a given bucket, only one event notification rule can be created per queue.
  • Each bucket can have up to 5 event notification rules.
  • Deletes that occur as a result of object lifecycle policies will not trigger an event notification.