# Bucket event notifications (webhooks): start work automatically on upload

https://www.gyrohosting.com/en/knowledgebase/article/s3-bucket-event-notifications-webhook

- **What you will learn**: how to notify your own application the moment a file is uploaded to or deleted from your bucket, how to verify that the call really came from us, and how to receive it only for the files you care about.
- **Time**: 7 minutes

## 1. What it does

| Event | When |
| --- | --- |
| `storage.object.created` | a file was uploaded, copied, or a multipart upload completed |
| `storage.object.deleted` | a file was deleted (Protected Storage: a delete marker or a version deletion) |
| `storage.objects.deleted_bulk` | several files were deleted in one request (names are not listed) |
| `storage.test` | "Send test" in the panel or the API |

The notification never contains the file: you get the bucket, the key, size, ETag, content type and time.

## 2. Setup in the panel

Service → **Management** → **Advanced** → **Event notifications** → **Add webhook** next to the bucket. Enter an `https://` address (port 443 or 8443), choose the events, optionally a **prefix** (e.g. `images/`) and **extensions** (e.g. `.jpg, .png`), then **Save**. The **secret** is shown once: store it. Try it with **Send test**; the result appears under **Recent deliveries**.

## 3. API, gyro CLI and Terraform

```
gyro storage events add 12345 gyro-proje --url https://example.com/s3-events \
  --events storage.object.created --prefix images/ --suffix .jpg,.png
gyro storage events test 12345 7
gyro storage events usage 12345
```

```
resource "gyro_storage_bucket_notification" "thumbnails" {
  service_id = 12345
  bucket     = "gyro-proje"
  url        = "https://example.com/s3-events"
  events     = ["storage.object.created"]
  prefix     = "images/"
  suffix     = [".jpg", ".png"]
}
```

API reference: [developer docs](https://www.gyrohosting.com/developers/en/howto/s3-events.html). Gyro MCP tool: `create_bucket_event`.

## 4. Verify the signature

Headers: `X-Gyro-Event`, `X-Gyro-Delivery` (unique id), `X-Gyro-Timestamp` (Unix seconds), `X-Gyro-Signature` = `sha256=` + HMAC-SHA256(secret, timestamp + `.` + raw body). Reject requests whose timestamp is older than 5 minutes. Lost the secret? Use **Rotate secret**.

## 5. Delivery

- At least once (rarely twice): drop repeats with `X-Gyro-Delivery`. No ordering guarantee: use `event_time`.
- Answer with **2xx within 6 seconds**; otherwise it is retried **8 times** over about 2 hours.
- **20 failures in a row** disable the webhook and you get an e-mail; fix the endpoint and press **Enable**.
- Requests come from **45.87.174.151, 45.87.174.153 and 45.87.174.154**. Only public internet addresses are accepted as targets.

## 6. Price and limits

|  |  |
| --- | --- |
| Free | **10,000 events per bucket per month** |
| Event pack (valid this month) | +1,000,000 events **€0.32** · +10,000,000 **€3.25** · +50,000,000 **€16.29** (excl. VAT) |
| Overage invoice | **None.** When the allowance is used up new events are not sent (your buckets are not affected); e-mails at 80 % and 100 %. Buying a pack resumes sending at once. |
| Webhooks | 5 per bucket, 20 per service (support ticket to raise) |
| Filters | prefix (max 512 characters), at most 10 extensions |

## 7. FAQ

**Do lifecycle deletions produce events?**

No, only S3 requests (upload, copy, delete). **Can I see which files a bulk delete removed?** No, `storage.objects.deleted_bulk` does not list them. **Why is the size empty?** The file was deleted right before the event was processed. **Protected Storage?** Yes; uploads include `version_id`.
