Kova olay bildirimleri (webhook): dosya yüklenince otomatik iş başlatma
1. Ne işe yarar?
Bir müşteriniz sitenize fotoğraf yükledi; küçük resminin hemen hazır olmasını istiyorsunuz. Kovayı dakikada bir taramak yerine kova olayı tanımlarsınız: dosya kovaya yazıldığı anda adresinize bir HTTPS isteği gelir, uygulamanız işi başlatır.
| Olay | Ne zaman gelir |
|---|---|
storage.object.created |
Dosya yüklendi, kopyalandı ya da çok parçalı yükleme tamamlandı |
storage.object.deleted |
Dosya silindi (Korumalı Depolama'da: silme işareti ya da sürüm silme) |
storage.objects.deleted_bulk |
Tek istekle birden çok dosya silindi (dosya adları listelenmez) |
storage.test |
Panelden ya da API'den "Test gönder" |
Bildirimde dosyanın kendisi yoktur: kova adı, dosya yolu (anahtar), boyut, ETag, içerik türü ve zaman gelir.
2. Panelden kurulum
- Hizmetinize girin → Yönetim → Gelişmiş → Olay bildirimleri.
- Kovanın yanındaki Webhook ekle'ye basın.
- Hedef adres:
https://ile başlayan adresiniz (port 443 ya da 8443). - Olaylar: istediklerinizi işaretleyin.
- İsterseniz Önek (ör.
resimler/) ve Uzantılar (ör..jpg, .png) yazın; yalnız bunlara uyan dosyalar için bildirim gelir. - Kaydet'e basın. Ekranda gizli anahtar bir kez gösterilir: uygulamanıza kaydedin.
- Test gönder ile deneyin; sonuç Son teslimler listesinde görünür.
3. API, gyro CLI ve Terraform
gyro storage events add 12345 gyro-proje --url https://ornek.com/s3-olay \
--events storage.object.created --prefix resimler/ --suffix .jpg,.png
gyro storage events test 12345 7
gyro storage events deliveries 12345 7
gyro storage events usage 12345
resource "gyro_storage_bucket_notification" "kucuk_resim" {
service_id = 12345
bucket = "gyro-proje"
url = "https://ornek.com/s3-olay"
events = ["storage.object.created"]
prefix = "resimler/"
suffix = [".jpg", ".png"]
}
API: POST /cloud/storage/{id}/buckets/{bucket}/events, ayrıntılar geliştirici belgesinde. Yapay zekâ asistanınızla Gyro MCP üzerinden de (create_bucket_event) kurabilirsiniz.
4. İmzayı doğrulayın
Her istekte şu başlıklar vardır:
X-Gyro-Event: olay türüX-Gyro-Delivery: bu teslimin tekil kimliğiX-Gyro-Timestamp: gönderim zamanı (Unix saniye)X-Gyro-Signature:sha256=+ HMAC-SHA256(gizli anahtar,X-Gyro-Timestamp+.+ ham gövde)
const sig = 'sha256=' + crypto.createHmac('sha256', SECRET).update(ts + '.' + rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.headers['x-gyro-signature']))) return res.status(401).end();
Zaman damgası 5 dakikadan eskiyse isteği reddetmenizi öneririz. Gizli anahtarı kaybederseniz panelden Gizli anahtarı yenile ile yenisini alırsınız.
Örnek gövde:
{"id":"0b3c7c9e-6a0e-4c43-9b7b-2f5f1c1c9a11","event":"storage.object.created","created_at":"2026-11-15T10:12:04+03:00",
"data":{"service_id":12345,"bucket":"gyro-proje","key":"resimler/kapak.jpg","size":248133,"etag":"9b2cf535f27731c974343645a3985328",
"content_type":"image/jpeg","method":"put","source":"api","event_time":"2026-11-15T10:12:04+03:00"}}
5. Teslim nasıl çalışır?
- En az bir kez: aynı olay nadiren iki kez gelebilir.
X-Gyro-Deliveryile tekrarı ayıklayın. - Sıra garantisi yoktur: olaylar oluşma sırasıyla gelmeyebilir;
event_time'a bakın. - 6 saniye içinde 2xx yanıt verin. Uzun işi arka plana alın.
- 2xx dışı yanıt ya da zaman aşımında 8 kez yeniden denenir (1 dakikadan başlayıp artarak, yaklaşık 2 saat).
- Adres art arda 20 kez hata verirse webhook kapanır ve size e-posta gelir. Düzelttikten sonra panelden Etkinleştir'e basın.
- Bildirimler 45.87.174.151, 45.87.174.153 ve 45.87.174.154 adreslerinden gelir; güvenlik duvarınızda izin verin.
- Güvenlik için yalnız genel internetteki adreslere gönderilir; yerel ve özel ağ adresleri kabul edilmez.
6. Fiyat ve sınırlar
| Ücretsiz hak | Her kova için ayda 10.000 olay |
| Olay paketi (o ay geçerli) | +1.000.000 olay 0,32 € · +10.000.000 olay 3,25 € · +50.000.000 olay 16,29 € (KDV hariç) |
| Aşım faturası | Yok. Hak dolunca yeni olaylar gönderilmez, kovalarınız etkilenmez; %80 ve %100'de e-posta gelir. Paket alınca gönderim hemen sürer. |
| Webhook sayısı | Kova başına 5, hizmet başına 20 (artırmak için destek talebi) |
| Süzgeç | Önek (en çok 512 karakter), en çok 10 uzantı |
Fiyatlar panelde Türk lirası olarak gösterilir. Test olayları hakkınızdan düşmez.
7. Sık sorulan sorular
Yaşam döngüsü kuralının sildiği dosyalar için olay gelir mi?
Hayır. Yalnız S3 istekleriyle (yükleme, kopyalama, silme) yapılan değişiklikler olay üretir.
Toplu silmede hangi dosyaların silindiğini görebilir miyim?
storage.objects.deleted_bulk olayında dosya adları listelenmez. Gerekiyorsa silme işlemini tek tek yapın ya da kovayı listeleyin.
Olay geldiğinde dosyanın boyutu neden boş?
Dosya, olay işlenmeden hemen önce silindiyse boyut ve ETag gönderilemez.
Korumalı Depolama'da çalışır mı?
Evet. Yüklemede version_id de gelir; silmede (silme işareti) storage.object.deleted gelir.
AWS S3 olay bildirimleriyle aynı mı?
Mantık aynıdır; gövde biçimi Gyro'nundur ve hesap webhook'larımızla aynı imzayı kullanır. Ayrı bir kuyruk hizmeti kurmanız gerekmez.
Geri bildiriminiz için teşekkürler!
