Skip to content
0850 554 5439 [email protected]

How can we help?

Search our guides and tutorials, or browse the categories below.

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

Object Storage (S3) 108 views Step-by-step guide Last verified: Markdown
What you will learnhow 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.
Time7 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

bash
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
hcl
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: 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.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.