Event Notifications

Send events to an HTTPS endpoint, Kafka topic, or RabbitMQ exchange when objects in a Stook Bucket are created or removed.

Configure Event Notifications to send object creation and removal events from a Stook Bucket to an external destination.

Stook supports HTTPS, Kafka, and AMQP destinations. Event Notifications can be used to trigger application workflows when objects are uploaded, copied, or removed without repeatedly listing the bucket for changes.

How Event Notifications Work

Event Notifications consist of two components:

• A destination defines where Stook sends events. A destination belongs to an organization and a specific region. Multiple Stook Buckets can use the same destination.

• A notification is a rule configured on a Stook Bucket. It defines which events are sent to a destination and can optionally filter objects by key prefix or suffix.

Create the destination first, then configure one or more notifications on the Stook Bucket.

A Stook Bucket can use only destinations created in the same region as the bucket.

For complete API details, see:

• Notification Destinations API

• Bucket Settings API

Destination Types

Type	Endpoint example	Delivery behavior
HTTPS	https://api.example.com/stook-hook	Sends each event to the endpoint as an HTTP POST request with a JSON body.
Kafka	kafka://kafka.example.com:9092	Writes each event to the Kafka topic with the same name as the destination.
AMQP	amqp://mq.example.com:5672	Publishes each event to the configured RabbitMQ exchange using the destination name as the routing key.

All destination types receive the same event JSON structure.

Create a Destination

Destinations are managed separately from individual Stook Buckets.

In the Medianova Control Panel, select Stook Object Storage → Event Notifications and create a destination.

Destination Settings

Setting	Description
Name	Destination name. Must contain 3–63 letters, numbers, hyphens, or underscores and be unique within the region. For Kafka, the name is also the topic name. For AMQP, it is used as the routing key.
Region	Region containing the Stook Buckets that will use the destination.
Type	Destination type: HTTPS, Kafka, or AMQP.
Endpoint	Address to which Stook sends events.
Exchange	AMQP only. RabbitMQ exchange to which events are published. If empty, amq.topic is used.
Persistent	Queues events that cannot be delivered and retries them. Off by default.
Retry settings	Configures maximum retries, time to live, and the interval between retries when Persistent is enabled.

The Exchange value can contain letters, numbers, hyphens, underscores, periods, and colons and can be up to 127 characters.

When Persistent is enabled, the following retry ranges apply:

• Maximum retries: 1–100

• Time to live: 1–1,209,600 seconds

• Wait between retries: 0–3,600 seconds

The maximum time to live is 14 days.

When Persistent is disabled, an event that cannot be delivered is dropped. Enable Persistent when events must be retried after temporary destination failures.

The destination Name, Region, and Type cannot be changed after creation. To change one of these values, create a new destination and move the associated notifications to it.

Prepare the Destination

Configure the destination system before adding it to Stook.

HTTPS

Configure the endpoint to accept HTTP POST requests containing a JSON body.

Kafka

Create a Kafka topic with the same name as the Stook destination.

AMQP

Create the required exchange in RabbitMQ. Stook does not create the exchange.

If no exchange is specified, amq.topic is used. Bind a queue to the exchange using the destination name as the routing key. For a topic exchange, # can also be used to receive the events.

Endpoint Requirements

Destination endpoints must meet the following requirements:

• HTTPS destinations must use https://. Plain http:// endpoints are not accepted.

• Kafka destinations must use kafka://.

• AMQP destinations must use amqp:// or amqps://.

• The endpoint must use a hostname rather than an IP address.

• The hostname must resolve to a public address.

• Private, loopback, and link-local addresses are not accepted.

• The endpoint must be reachable from the internet on the configured port.

• HTTPS endpoints must present a valid TLS certificate. Self-signed certificates are not accepted.

Add a Notification to a Stook Bucket

1

Open the Stook Bucket

In the Medianova Control Panel, select Stook Object Storage → Buckets, then select the Stook Bucket you want to configure.

2

Open Notifications

On the Bucket configuration page, select Notifications, then select Add notification.

3

Configure the notification

Configure the following fields:

• Destination — Select a destination in the same region as the Stook Bucket.

• Events — Select one or more events.

• Prefix — Optional. Send events only for object keys that start with the specified value, such as incoming/.

• Suffix — Optional. Send events only for object keys that end with the specified value, such as .jpg.

Leave Prefix and Suffix empty to apply the notification to the entire Stook Bucket.

4

Save the configuration

Select Save Changes.

A Stook Bucket can have up to 10 notifications.

To remove a notification, select Remove next to the notification, then select Save Changes.

Supported Events

Event	Trigger
s3:ObjectCreated:*	Any supported object creation event.
s3:ObjectCreated:Put	An object is uploaded in a single request.
s3:ObjectCreated:Post	An object is uploaded using an HTML form.
s3:ObjectCreated:Copy	An object is created through a server-side copy.
s3:ObjectCreated:CompleteMultipartUpload	A multipart upload is completed.
s3:ObjectRemoved:*	Any supported object removal event.
s3:ObjectRemoved:Delete	An object is deleted.
s3:ObjectRemoved:DeleteMarkerCreated	A delete marker is created in a versioned Stook Bucket.
s3:ObjectSynced:*	An object is synchronized between zones.

Lifecycle expiration events (s3:ObjectLifecycleExpiration:*) are not supported.

Event Format

HTTPS, Kafka, and AMQP destinations receive events using the same JSON structure.

The event payload includes information about the event, Stook Bucket, object, and request that triggered the notification.

Commonly used fields include:

Field	Description
eventName	Event that occurred, such as ObjectCreated:Put or ObjectRemoved:Delete.
eventTime	Time the event occurred, in UTC.
s3.bucket.name	Name of the Stook Bucket.
s3.object.key	Object key.
s3.object.size	Object size in bytes.
s3.object.eTag	Object ETag.
s3.configurationId	ID of the notification that generated the event.
responseElements.x-amz-request-id	ID of the request that caused the event. The same value is included for each destination receiving copies of that event.

The event source is identified as:

{
  "eventSource": "ceph:s3"
}

Delivery Behavior

The following behavior applies to Event Notifications:

• A Stook Bucket can use only destinations from its own region.

• Failure to deliver an event does not cause the corresponding upload or delete operation to fail.

• When Persistent is disabled, events are sent while the operation that triggered them is being processed. A slow destination can therefore increase the processing time of the triggering request.

• When Persistent is enabled, events are queued and delivered separately.

• A destination cannot be deleted while it is used by a Stook Bucket.

• Notifications are not copied when bucket settings are copied from one Stook Bucket to another.

Configure Event Notifications with the API

Manage Destinations

Use the notification destination endpoints to manage destinations:

GET    /api/v2/stook/{organization_uuid}/notification-destination
POST   /api/v2/stook/{organization_uuid}/notification-destination
GET    /api/v2/stook/{organization_uuid}/notification-destination/{destination_uuid}
PUT    /api/v2/stook/{organization_uuid}/notification-destination/{destination_uuid}
DELETE /api/v2/stook/{organization_uuid}/notification-destination/{destination_uuid}

HTTPS Destination

{
  "name": "order-hook",
  "region": "eu-ist-1",
  "kind": "https",
  "endpoint": "https://api.example.com/stook-hook"
}

Kafka Destination

{
  "name": "order-events",
  "region": "eu-ist-1",
  "kind": "kafka",
  "endpoint": "kafka://kafka.example.com:9092"
}

AMQP Destination

{
  "name": "order-events",
  "region": "eu-ist-1",
  "kind": "amqp",
  "endpoint": "amqp://mq.example.com:5672",
  "amqp_exchange": "orders"
}

The amqp_exchange field applies only to AMQP destinations.

Configure Bucket Notifications

Notifications are configured through the bucket settings endpoint:

PATCH /api/v2/stook/{organization_uuid}/bucket/{bucket_uuid}/settings

Send:

{
  "notifications": [
    {
      "destination_uuid": "<DESTINATION_UUID>",
      "events": [
        "s3:ObjectCreated:*"
      ],
      "prefix": "incoming/",
      "suffix": ".jpg"
    }
  ]
}

This request configures the Stook Bucket to send object creation events for .jpg objects under incoming/ to the specified destination.

The notifications array represents the complete notification configuration for the Stook Bucket. Notifications omitted from the request are removed.

To add a notification without removing existing notifications, retrieve the current list, append the new notification, and send the complete list. Keep the id values of existing notifications unchanged.

Troubleshooting

The destination is in a different region

A Stook Bucket can use only destinations in the same region.

Select an existing destination from the bucket's region or create a new destination in that region.

An event is not supported

Select an event listed under Supported Events.

Lifecycle expiration events are not supported.

The Stook Bucket already has 10 notifications

A Stook Bucket supports up to 10 notifications.

Remove an existing notification or combine multiple events into one notification.

A destination cannot be deleted

A destination cannot be deleted while notifications reference it.

Remove the notifications using the destination from all applicable Stook Buckets, then delete the destination.

The destination hostname cannot be resolved

Confirm that the endpoint uses a valid hostname that resolves through public DNS.

The destination is not publicly reachable

Use an endpoint that resolves to a public address and is reachable from the internet on the configured port.

The destination uses an invalid protocol

Use the protocol required by the destination type:

• HTTPS: https://

• Kafka: kafka://

• AMQP: amqp:// or amqps://

The Exchange field is rejected

The Exchange field can be configured only for AMQP destinations.

For HTTPS and Kafka destinations, leave Exchange empty.

Events are not received

Confirm that:

• The notification's selected events match the operation being performed.

• The object's key matches the configured Prefix and Suffix, if specified.

• The destination endpoint is reachable from the internet.

For each destination type, also verify:

• HTTPS — The endpoint presents a valid TLS certificate.

• Kafka — A topic with the same name as the destination exists.

• AMQP — The exchange exists and a queue is bound to it using the destination name as the routing key.

If the destination was temporarily unavailable while Persistent was disabled, events generated during that period are not delivered again.

Related Topics

• Bucket Configuration

• Versioning