Teslimat başlıkları
| Başlık | Örnek | Ne işe yarar |
|---|---|---|
| X-WC-Webhook-Source | Sitenin adresi | İsteğin hangi siteden geldiği |
| X-WC-Webhook-Topic | order.updated | Konu |
| X-WC-Webhook-Resource | order | Kaynak |
| X-WC-Webhook-Event | updated | Olay |
| X-WC-Webhook-Signature | base64 metin | Gövdenin HMAC-SHA256 imzası |
| X-WC-Webhook-ID | Sayı | Webhook kaydının numarası |
| X-WC-Webhook-Delivery-ID | Sayı | Teslim kaydının numarası |
Konuya göre işlem seçmek için gövdeyi açmadan X-WC-Webhook-Topic başlığına bakabilirsiniz. Ama işlemden önce imzayı mutlaka doğrulayın.
İmzayı doğrulama adımları
- İsteğin gövdesini JSON’a çevirmeden önce ham bayt olarak alın.
- Ham gövdenin HMAC-SHA256 özetini webhook’ta tanımlı gizli anahtarla hesaplayın.
- Sonucu base64 ile kodlayın.
- Bulduğunuz değeri X-WC-Webhook-Signature başlığıyla sabit zamanlı bir karşılaştırma işleviyle karşılaştırın.
- Eşleşmiyorsa isteği işlemeyin ve 401 döndürün.
En sık hata, gövdeyi önce JSON olarak çözüp sonra yeniden metne çevirerek imzalamaktır. Boşluklar ve alan sırası değişeceği için imza tutmaz. Gövdeyi değiştiren vekil sunucular ya da güvenlik katmanları da aynı sonuca yol açar.
Reddetmenin bir yan etkisi var: 2xx dışındaki her yanıt hata sayılır ve art arda hatalar webhook’u devre dışı bırakır. Anahtar uyuşmazlığını fark ettiğinizde hemen düzeltin.
Gövdede ne gelir?
| Konu türü | Gövde |
|---|---|
| Ürün, sipariş, müşteri, kupon | Kaynağın REST API’de döndüğü nesnenin aynısı |
| action.EYLEM_ADI | Eylemin ilk argümanı, ör. sepete eklemede cart_item_key |
Sipariş webhook’unda gövde, GET /orders/ID yanıtındaki nesnedir: durum, kalemler, adresler ve iadeler dahil. Bu yüzden çoğu durumda ek bir API çağrısına gerek kalmaz. Yine de gövde teslim anındaki durumu yansıtır; sonraki değişiklikler için yeni bildirim gelir.
Güvenilir işleme önerileri
- Bildirimi hızla kaydedip 2xx döndürün, asıl işi kuyrukta yapın. Uzun süren işlem zaman aşımına ve hata sayımına yol açar.
- Aynı kaydın kısa sürede birden çok updated bildirimi gelebilir; işleminizi aynı bildirim iki kez gelse de aynı sonucu verecek şekilde kurun.
- Teslim numarasını kayıtlarınıza yazın; WooCommerce günlüğüyle eşleştirmeyi kolaylaştırır.
- Webhook devre dışı kalabilir ya da bildirim kaçabilir. Belirli aralıklarla API’den okuyarak eksikleri tamamlayın.
Sık hatalar
| Belirti | Neden | Çözüm |
|---|---|---|
| İmza her istekte tutmuyor | Gövde çözülüp yeniden yazıldıktan sonra imzalandı | Ham gövdeyi kullanın |
| İmza bazen tutmuyor | Araya giren katman gövdeyi değiştiriyor | Vekil sunucu ve güvenlik ayarlarını kontrol edin |
| Tüm istekler 401 | Alıcıdaki anahtar webhook’taki anahtarla aynı değil | Anahtarı iki tarafta yeniden eşitleyin |
| Başlık bulunamıyor | Başlık adının büyük küçük harfine bakılıyor | Başlık adlarını harf duyarsız okuyun |
Sık sorulanlar
X-WC-Webhook-Signature nasıl hesaplanır?
İstek gövdesinin, webhook’taki gizli anahtarla hesaplanan HMAC-SHA256 özetinin base64 karşılığıdır. Alıcı aynı hesabı ham gövde üzerinde yapar.
İmza neden tutmuyor?
Genellikle gövde imzalanmadan önce JSON olarak çözülüp yeniden yazılmıştır ya da gizli anahtar farklıdır. Ham gövdeyi ve anahtarı kontrol edin.
Webhook gövdesinde sipariş ayrıntıları var mı?
Evet. Belgeye göre ürün ve sipariş gibi kaynaklarda gövde, REST API’nin o kaynak için döndüğü nesnenin aynısıdır.
İmzası geçersiz isteğe ne döndürmeliyim?
401 gibi bir hata kodu döndürüp isteği işlemeyin. Ama art arda hatalar webhook’u devre dışı bırakacağı için anahtar sorununu hızla çözün.
Kaynaklar
İlgili WooCommerce API konuları
Son güncelleme: 27.10.2026 · WooCommerce API rehberinin tamamı