Bucket event notifications (webhooks): start work automatically on upload
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. 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: useevent_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.
Thanks for your feedback!
