> For the complete documentation index, see [llms.txt](https://clients.medianova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://clients.medianova.com/products/object-storage-stook/bucket-configuration/event-notifications.md). # 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. {% hint style="info" %} A Stook Bucket can use only destinations created in the same region as the bucket. {% endhint %} {% hint style="info" %} For complete API details, see: * [Notification Destinations API](/api-documentation/object-storage-stook/notification-destinations.md) * [Bucket Settings API](/api-documentation/object-storage-stook/buckets/settings.md) {% endhint %} ## Destination Types
TypeEndpoint exampleDelivery behavior
HTTPShttps://api.example.com/stook-hookSends each event to the endpoint as an HTTP POST request with a JSON body.
Kafkakafka://kafka.example.com:9092Writes each event to the Kafka topic with the same name as the destination.
AMQPamqp://mq.example.com:5672Publishes 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](https://cloud.medianova.com), select **Stook Object Storage → Event Notifications** and create a destination. ### Destination Settings
SettingDescription
NameDestination 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.
RegionRegion containing the Stook Buckets that will use the destination.
TypeDestination type: HTTPS, Kafka, or AMQP.
EndpointAddress to which Stook sends events.
ExchangeAMQP only. RabbitMQ exchange to which events are published. If empty, amq.topic is used.
PersistentQueues events that cannot be delivered and retries them. Off by default.
Retry settingsConfigures 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. {% hint style="warning" %} When **Persistent** is disabled, an event that cannot be delivered is dropped. Enable **Persistent** when events must be retried after temporary destination failures. {% endhint %} 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 {% stepper %} {% step %} ### **Open the Stook Bucket** In the [Medianova Control Panel](https://cloud.medianova.com), select **Stook Object Storage → Buckets**, then select the Stook Bucket you want to configure. {% endstep %} {% step %} ### **Open Notifications** On the **Bucket configuration** page, select **Notifications**, then select **Add notification**.
{% endstep %} {% step %} ### **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. {% endstep %} {% step %} ### **Save the configuration** Select **Save Changes**. {% endstep %} {% endstepper %} 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: ```json { "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: ```http 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 ```json { "name": "order-hook", "region": "eu-ist-1", "kind": "https", "endpoint": "https://api.example.com/stook-hook" } ``` ### Kafka Destination ```json { "name": "order-events", "region": "eu-ist-1", "kind": "kafka", "endpoint": "kafka://kafka.example.com:9092" } ``` ### AMQP Destination ```json { "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: ```http PATCH /api/v2/stook/{organization_uuid}/bucket/{bucket_uuid}/settings ``` Send: ```json { "notifications": [ { "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. {% hint style="warning" %} 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. {% endhint %} ## 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](/products/object-storage-stook/bucket-configuration.md) * [Versioning](/products/object-storage-stook/bucket-configuration/versioning.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://clients.medianova.com/products/object-storage-stook/bucket-configuration/event-notifications.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.