# Kova olay bildirimleri (webhook): dosya yüklenince otomatik iş başlatma

https://www.gyrohosting.com/bilgi-bankasi/makale/s3-kova-olay-bildirimleri-webhook

- **Bu rehberde ne öğreneceksiniz**: Kovanıza bir dosya yüklendiğinde ya da silindiğinde kendi uygulamanıza anında haber göndermeyi; bildirimin gerçekten bizden geldiğini imzayla doğrulamayı; yalnız istediğiniz dosyalar için bildirim almayı.
- **Süre**: 7 dakika
- **Kimin için**: Yüklenen görselden küçük resim üreten, faturayı işleyen, virüs taraması ya da arama indeksi çalıştıran ekipler.
- **Gerekenler**: Gyro Nesne Depolama ya da Korumalı Depolama hizmeti ve internetten erişilebilen bir HTTPS adresi.

## 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

1. Hizmetinize girin → **Yönetim** → **Gelişmiş** → **Olay bildirimleri**.
2. Kovanın yanındaki **Webhook ekle**'ye basın.
3. **Hedef adres**: `https://` ile başlayan adresiniz (port 443 ya da 8443).
4. **Olaylar**: istediklerinizi işaretleyin.
5. İsterseniz **Önek** (ör. `resimler/`) ve **Uzantılar** (ör. `.jpg, .png`) yazın; yalnız bunlara uyan dosyalar için bildirim gelir.
6. **Kaydet**'e basın. Ekranda **gizli anahtar** bir kez gösterilir: uygulamanıza kaydedin.
7. **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](https://www.gyrohosting.com/developers/tr/howto/s3-events.html). 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ği
- `X-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-Delivery` ile 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.
