# GetBucketNotificationConfiguration

GetBucketNotificationConfiguration reports which event notifications a bucket sends - the
messages Amazon S3 can deliver to a topic, a queue or a function when an object is created or
deleted. Bucket event notifications are not part of STRG, so there is never anything to
report: the operation checks that the bucket exists and answers with an empty
`NotificationConfiguration` document - the same answer Amazon S3 gives for a bucket with no
notifications. Tools that read it while describing a bucket work unchanged.

The deprecated [GetBucketNotification](https://docs.strg.com/s3-api/GetBucketNotification) sends the same request and
gets the same answer; this operation is the better choice for new code.

**Info: Good to know on STRG**

- Event notifications are not part of STRG, so the answer never contains a
  `TopicConfiguration`, `QueueConfiguration`, `CloudFunctionConfiguration` or
  `EventBridgeConfiguration`.
- PutBucketNotificationConfiguration is answered with `501 NotImplemented`, so a client knows
  straight away.
- `x-amz-expected-bucket-owner` is welcome and has nothing to check: a key only ever reaches
  buckets of its own account.

## When you'd use it

- **Tools that describe a bucket.** Infrastructure-as-code tools, backup tools and inventory
  scripts written for Amazon S3 read every bucket setting they know about, notifications
  included. On STRG the request succeeds with the empty answer, so the description
  completes without errors.
- **Code that checks before relying on events.** An application that looks at a bucket's
  notification configuration before deciding how to learn about new objects finds it empty,
  and can fall back to listing the bucket - for example with
  [ListObjectsV2](https://docs.strg.com/s3-api/ListObjectsV2) on a schedule.

## Request

```http
GET /?notification HTTP/1.1
Host: my-bucket.s3.eu-central-1.strg.com
Authorization: AWS4-HMAC-SHA256 Credential=...
x-amz-date: 20260926T120000Z
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

The path-style form is `GET /my-bucket?notification` on `s3.eu-central-1.strg.com` -
[Addressing](https://docs.strg.com/s3-api/overview#addressing) explains both.

### Permissions

The access key needs **Read bucket settings** (`buckets:read-config`). Every access key holds
it, whether it covers all buckets or only some - a key scoped to specific buckets reads only
those. [Access keys](https://docs.strg.com/access-keys) has the details.

### URI parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Bucket` | String | Yes | The bucket whose notification configuration to read. |
| `notification` | Flag | Yes | Selects this operation. Sent with no value. |

Any other query parameter is answered with `501 NotImplemented`, so a client knows straight away
that it has no effect here.

### Request headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `x-amz-expected-bucket-owner` | String | No | Welcome, with nothing to check: an access key only ever reaches its own account's buckets. |

### Request body

None.

## Response

A successful request answers `200 OK` with an XML body.

### Response headers

| Name | Description |
| --- | --- |
| `Content-Type` | `application/xml`. |
| `x-amz-request-id` | The request ID, handy for a support request. |

### Response body

The document's root element is always empty; the elements Amazon S3 can place inside it are
listed so a reader knows what to expect of them:

| Element | Type | Description |
| --- | --- | --- |
| `NotificationConfiguration` | Container | The root element. Always empty on STRG. |
| `TopicConfiguration` | Container | Not sent. On Amazon S3, a topic that receives notifications. |
| `QueueConfiguration` | Container | Not sent. On Amazon S3, a queue that receives notifications. |
| `CloudFunctionConfiguration` | Container | Not sent. On Amazon S3, a function invoked for notifications. |
| `EventBridgeConfiguration` | Container | Not sent. On Amazon S3, marks delivery of events to an event bus as enabled. |

```xml
<?xml version="1.0" encoding="UTF-8"?>
<NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"/>
```

## Errors

These are the errors this request can return, and the situation behind each one.

| Code | HTTP status | When |
| --- | --- | --- |
| `NoSuchBucket` | 404 | The bucket does not exist, belongs to another account, is in a region other than the endpoint's, or the account stores nothing in the endpoint's region yet. |
| `AccessDenied` | 403 | The access key is scoped to buckets that do not include this one, or the account is not active. |
| `InvalidAccessKeyId` | 403 | The access key does not exist, has expired or been revoked - or it was created moments ago and is not usable yet in a region where the account already stores data, in which case the same request works shortly afterwards. |
| `SignatureDoesNotMatch` | 403 | The request signature does not match. |
| `RequestTimeTooSkewed` | 403 | The request time is more than 15 minutes from the server's. |
| `AuthorizationHeaderMalformed` | 400 | The signature's credential scope names a region other than the endpoint's. |
| `NotImplemented` | 501 | The request carries a query parameter this operation does not accept. |
| `SlowDown` | 503 | Too many requests. The `Retry-After` header says when a retry is welcome; the AWS SDKs retry on their own. |
| `ServiceUnavailable` | 503 | A temporary failure; the same request can be retried. |
| `InternalError` | 500 | An unexpected failure while checking the bucket; the same request can be retried. |

## Differences from Amazon S3

The table lists each place where STRG behaves differently, and what that means for a client.

| Aspect | Amazon S3 | STRG |
| --- | --- | --- |
| Event notifications | Configurable per bucket, to topics, queues, functions or an event bus | Not part of STRG. The answer is always the empty document |
| Setting them | PutBucketNotificationConfiguration | Answered with `501 NotImplemented` |
| Bucket in another region | `301` redirect with `x-amz-bucket-region` | `404 NoSuchBucket`. A bucket is reached through its own regional endpoint. |
| Nothing stored in the endpoint's region yet | Any valid key reaches the endpoint | `404 NoSuchBucket`, the truthful answer: there is no bucket there |
| `x-amz-expected-bucket-owner` | Checked against the bucket owner | Welcome, with nothing to check |

## Examples

Reading the notification configuration of `my-bucket` in `eu-central-1`:

**AWS CLI**

```bash
aws s3api get-bucket-notification-configuration \
  --bucket my-bucket \
  --endpoint-url https://s3.eu-central-1.strg.com \
  --region eu-central-1
```

The command succeeds and prints nothing, because the configuration is empty.

**Python (boto3)**

```python
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.eu-central-1.strg.com",
    region_name="eu-central-1",
)

response = s3.get_bucket_notification_configuration(Bucket="my-bucket")
print(response.get("TopicConfigurations", []))
print(response.get("QueueConfigurations", []))
print(response.get("LambdaFunctionConfigurations", []))
```

**JavaScript (AWS SDK v3)**

```javascript
import { GetBucketNotificationConfigurationCommand, S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  endpoint: "https://s3.eu-central-1.strg.com",
  region: "eu-central-1",
});

const response = await client.send(
  new GetBucketNotificationConfigurationCommand({ Bucket: "my-bucket" }),
);
console.log(response.TopicConfigurations ?? []);
console.log(response.QueueConfigurations ?? []);
console.log(response.LambdaFunctionConfigurations ?? []);
```

## Related

- [GetBucketNotification](https://docs.strg.com/s3-api/GetBucketNotification) - the deprecated form of this operation
- [GetBucketAccelerateConfiguration](https://docs.strg.com/s3-api/GetBucketAccelerateConfiguration)
- [ListObjectsV2](https://docs.strg.com/s3-api/ListObjectsV2)
- [Access keys](https://docs.strg.com/access-keys)
- [S3 API overview](https://docs.strg.com/s3-api/overview#supported-operations) - including the [other S3 operations](https://docs.strg.com/s3-api/overview#other-s3-operations)