Olaylar
| Alan | Olay | Ne zaman gelir |
|---|---|---|
| Sipariş | order.paid | Sipariş ödendiğinde |
| Sipariş | order.canceled | Satıcı iptal başlattığında |
| Sipariş | order.shipped | Siparişe kargo bilgisi eklendiğinde |
| Sipariş | order.delivered | Sipariş teslim edildi olarak işaretlendiğinde |
| İlan | listing.created, listing.updated, listing.deleted | İlan açıldığında, başlık, görsel, durum gibi alanlar değiştiğinde, silindiğinde |
| Envanter | inventory.created, inventory.updated, inventory.deleted | Ürün eklendiğinde; fiyat, SKU, durum ya da işlem profili değiştiğinde; silindiğinde |
| Envanter | inventory.out_of_stock | Bir ürünün adedi 0'a indiğinde |
Etsy yeni olayları GitHub'daki open-api deposunun duyuru alanında ilan eder. Stok senkronu yapan bir sistem için inventory.out_of_stock ve order.paid en işe yarayan iki olaydır.
Bildirim gövdesi
Tüm bildirimler event_type, resource_url ve shop_id alanlarını taşır. İlan olaylarında listing_id, envanter olaylarında listing_id ve product_id de bulunur. resource_url, güncel veriyi almak için çağıracağınız hazır adrestir: sipariş olayında receipt, ilan olayında ilan, envanter olayında ürün ucunu gösterir.
Bildirimin kendisi veri taşımaz. Bu yüzden her bildirimde resource_url çağrılır; bu da istek kotasından düşer.
İmza doğrulama
Her istekte üç başlık gelir: webhook-id, webhook-timestamp ve webhook-signature (Etsy: Webhooks).
- İmzalanan metni kurun: webhook-id, nokta, webhook-timestamp, nokta ve ham gövde. Gövdeyi JSON olarak çözmeden önceki hâliyle kullanın.
- Portaldaki imza anahtarının başındaki whsec_ önekini atıp kalanını Base64 ile çözün.
- Bu anahtarla HMAC-SHA256 hesaplayıp sonucu Base64 ile kodlayın.
- webhook-signature başlığındaki değerlerden biri sizin sonucunuzla eşleşmiyorsa isteği reddedin.
- Tekrar saldırılarına karşı webhook-timestamp ile sunucu saatiniz arasındaki farkı ölçün; Etsy örneği 300 saniyeden eskiyi reddeder.
Yeniden deneme ve izleme
Uç adresiniz bildirimi kabul etmezse Etsy artan aralıklarla yeniden dener:
| Deneme | Bekleme |
|---|---|
| 1 | Hemen |
| 2 | 5 saniye |
| 3 | 5 dakika |
| 4 | 30 dakika |
| 5 | 2 saat |
| 6 | 5 saat |
| 7 ve 8 | 10'ar saat |
Portalda teslim istatistikleri, her denemenin sonucu ve gelen gövdeler görünür. Başarısız mesajlar elle ya da belirli bir tarihten itibaren toplu olarak yeniden gönderilebilir. Test sekmesi, imza doğrulamanızı canlı veriye dokunmadan denemenizi sağlar.
Sık sorulanlar
Etsy webhook kimlere açık?
Etsy belgesine göre webhook hem ticari hem kişisel uygulamalarda kullanılabilir. Abonelik için geçerli bir OAuth token'ı ve Etsy'nin POST isteği gönderebileceği herkese açık bir adres gerekir.
Etsy webhook bildirimi sipariş ayrıntısını taşır mı?
Hayır. Bildirim olay türünü, shop_id'yi ve resource_url'yi taşır. Ayrıntı için resource_url çağrılır.
Aynı bildirim iki kez gelirse ne yapmalı?
webhook-id değeri yeniden denemelerde de aynı kalır. Bu değeri kaydedip daha önce işlenmiş bildirimi atlayın.
Adresim kapalıyken gelen bildirimler kaybolur mu?
Hemen kaybolmaz. Etsy sekiz denemeye kadar artan aralıklarla yeniden dener. Başarısız mesajları portaldan tek tek ya da bir tarihten itibaren toplu olarak yeniden gönderebilirsiniz.
Kaynaklar
İlgili Etsy API konuları
Son güncelleme: 27.10.2026 · Etsy API rehberinin tamamı