WP CLI ile WooCommerce Webhook Oluşturma ve Yönetimi

Tarafındankomut
0 Comments

E-ticaret projelerinde entegrasyon kelimesi duyulduğunda çoğu geliştiricinin aklına ilk gelen şey webhook’lar oluyor. WooCommerce, yerleşik webhook sistemiyle sipariş oluşturma, ödeme tamamlama, ürün güncelleme gibi onlarca olayı dışarıya bildirebiliyor. Peki bu webhook’ları WP-CLI üzerinden yönetmek neden bu kadar önemli? Çünkü 50 mağazası olan bir ajans senaryosunda, her mağaza için tek tek admin paneline girip webhook kurmak saatler alır. WP-CLI ile bunu dakikalar içinde, hatta toplu script’lerle saniyeler içinde halledebilirsiniz.

WooCommerce Webhook Sistemi Nedir?

WooCommerce webhook’ları, belirli bir olay gerçekleştiğinde tanımladığınız bir URL’ye HTTP POST isteği gönderen tetikleyicilerdir. Bir sipariş oluşturulduğunda ERP sisteminizi haberdar etmek, bir müşteri kaydolduğunda CRM’inize veri göndermek ya da stok azaldığında depo yönetim yazılımınızı uyarmak için kullanılır.

WP-CLI üzerinden webhook yönetimi için kullanacağımız komut ailesi şu şekilde:

wp wc webhook --help

Bu komut size mevcut alt komutları listeler:

  • create: Yeni webhook oluşturur
  • get: Mevcut webhook detaylarını getirir
  • list: Tüm webhook’ları listeler
  • update: Mevcut webhook’u günceller
  • delete: Webhook siler

Tüm WC komutlarında olduğu gibi, bir kullanıcı bağlamında çalışmanız gerekiyor. --user parametresini unutmayın, yoksa yetki hatası alırsınız.

İlk Webhook’u Oluşturmak

En basit senaryodan başlayalım. Bir sipariş oluşturulduğunda dış bir servise bildirim göndermek istiyorsunuz:

wp wc webhook create 
  --user=admin 
  --name="Siparis Olusturma Bildirimi" 
  --topic="order.created" 
  --delivery_url="https://api.sirketim.com/webhooks/woocommerce" 
  --status="active" 
  --secret="gizli-anahtar-buraya"

Bu komut başarılı çalıştığında size webhook ID’sini döner. Bu ID’yi saklayın, sonradan işinize yarayacak.

--secret parametresi önemli bir güvenlik katmanı. WooCommerce bu secret’ı kullanarak her isteğe X-WC-Webhook-Signature başlığı ekler. Alıcı taraf bu imzayı doğrulayarak isteğin gerçekten WooCommerce’den geldiğini teyit edebilir.

Desteklenen topic’lerin tam listesine bakmak için:

wp wc webhook list --user=admin --fields=id,name,topic,status

Tüm Desteklenen Topic’ler

WooCommerce’in desteklediği webhook topic’leri şunlardır:

  • coupon.created: Kupon oluşturulduğunda
  • coupon.updated: Kupon güncellendiğinde
  • coupon.deleted: Kupon silindiğinde
  • customer.created: Müşteri oluşturulduğunda
  • customer.updated: Müşteri güncellendiğinde
  • customer.deleted: Müşteri silindiğinde
  • order.created: Sipariş oluşturulduğunda
  • order.updated: Sipariş güncellendiğinde
  • order.deleted: Sipariş silindiğinde
  • product.created: Ürün oluşturulduğunda
  • product.updated: Ürün güncellendiğinde
  • product.deleted: Ürün silindiğinde

Webhook Listesi ve Filtreleme

Bir projede zamanla onlarca webhook birikebilir. Bunları düzenli takip etmek için:

wp wc webhook list --user=admin --format=table

Sadece aktif webhook’ları görmek için:

wp wc webhook list 
  --user=admin 
  --status=active 
  --fields=id,name,topic,delivery_url,status 
  --format=table

JSON formatında almak bazen otomasyon scriptlerinde çok daha kullanışlı:

wp wc webhook list --user=admin --format=json | python3 -m json.tool

Belirli bir webhook’un detaylarını görmek için:

wp wc webhook get 42 --user=admin

Bu komut size o webhook’un tüm özelliklerini, kaç kez tetiklendiğini, son teslimat tarihini ve mevcut durumunu gösterir.

Gerçek Dünya Senaryosu 1: ERP Entegrasyonu

Diyelim ki şirketin ERP sistemi SAP kullanıyor ve her tamamlanan sipariş için otomatik fatura oluşturması gerekiyor. Bu durumda “order.updated” topic’ini dinleyip sipariş durumu “completed” olduğunda ERP’ye bildirim göndermeniz gerekir.

wp wc webhook create 
  --user=admin 
  --name="SAP ERP - Tamamlanan Siparis" 
  --topic="order.updated" 
  --delivery_url="https://erp.sirket.com/api/wc-order-completed" 
  --status="active" 
  --secret="$(openssl rand -hex 32)" 
  --api_version="v3"

Burada $(openssl rand -hex 32) ile rastgele ve güçlü bir secret üretiyoruz. Bu pratiği mutlaka alışkanlık haline getirin.

--api_version parametresi de kritik. Webhook’ların gönderdiği payload formatı API versiyonuna göre değişiyor:

  • v1: Eski format, mümkünse kullanmayın
  • v2: Orta nesil
  • v3: Güncel format, tercih edin

Webhook Güncelleme

Bir webhook’un URL’si değiştiyse ya da geçici olarak devre dışı bırakmanız gerekiyorsa:

# Webhook'u devre dışı bırak
wp wc webhook update 42 
  --user=admin 
  --status="paused"

# Yeni URL'e yönlendir
wp wc webhook update 42 
  --user=admin 
  --delivery_url="https://yeni-api.sirket.com/webhook"

# Aynı anda birden fazla özellik güncelle
wp wc webhook update 42 
  --user=admin 
  --name="Guncellenmis Siparis Webhook" 
  --delivery_url="https://api-v2.sirket.com/orders" 
  --status="active"

Status değerleri şunlar olabilir:

  • active: Aktif, olaylar tetikleniyor
  • paused: Duraklatılmış, olaylar tetiklenmiyor ama webhook mevcut
  • disabled: Devre dışı
  • deliver_failed: WooCommerce tarafından otomatik olarak atanır, çok fazla başarısız teslimat olduğunda

deliver_failed durumu özellikle dikkat edilmesi gereken bir durum. WooCommerce, belirli sayıda başarısız teslimat denemesinden sonra webhook’u otomatik olarak bu statüye alır. Monitoring scriptinize bunu kontrol eden bir alarm ekleyin.

Gerçek Dünya Senaryosu 2: Çoklu Mağaza Kurulumu

Bir ajans olarak 20 farklı müşterinizin WooCommerce mağazası var ve hepsine aynı webhook konfigürasyonunu uygulamanız gerekiyor. Her birine tek tek admin panelinden giremezsiniz.

Şu script bunu otomatize eder:

#!/bin/bash

# Mağaza listesi - her satırda: domain|wp-path|webhook-secret
MAGAZALAR=(
  "magaza1.com|/var/www/magaza1|secret-magaza1-xyz"
  "magaza2.com|/var/www/magaza2|secret-magaza2-abc"
  "magaza3.com|/var/www/magaza3|secret-magaza3-def"
)

MERKEZI_API="https://merkez-panel.ajans.com/api/webhooks"

for magaza in "${MAGAZALAR[@]}"; do
  IFS='|' read -r domain wp_path secret <<< "$magaza"
  
  echo "=== $domain için webhook kuruluyor ==="
  
  # Sipariş webhook
  wp wc webhook create 
    --path="$wp_path" 
    --user=admin 
    --name="Merkez Panel - Siparis" 
    --topic="order.created" 
    --delivery_url="$MERKEZI_API/order-created?store=$domain" 
    --status="active" 
    --secret="$secret"
  
  # Ürün webhook  
  wp wc webhook create 
    --path="$wp_path" 
    --user=admin 
    --name="Merkez Panel - Urun Guncelleme" 
    --topic="product.updated" 
    --delivery_url="$MERKEZI_API/product-updated?store=$domain" 
    --status="active" 
    --secret="$secret"
    
  echo "=== $domain tamamlandı ==="
done

echo "Tüm mağazalar için webhook kurulumu tamamlandı."

Webhook Silme ve Temizlik

Eski entegrasyonlardan kalan, artık kullanılmayan webhook’lar hem gereksiz yük oluşturur hem de güvenlik riski taşır. Düzenli temizlik yapmak iyi bir alışkanlık:

# Tek webhook sil
wp wc webhook delete 42 --user=admin

# Birden fazla ID sil
wp wc webhook delete 42 56 78 --user=admin

# Onay istemeden sil (script'lerde kullanışlı)
wp wc webhook delete 42 --user=admin --force

Delivery failed durumundaki tüm webhook’ları toplu silmek için:

# Önce listeleyelim
FAILED_IDS=$(wp wc webhook list 
  --user=admin 
  --status=deliver_failed 
  --field=id 
  --format=ids)

echo "Silinecek webhook ID'leri: $FAILED_IDS"

# Emin olduktan sonra sil
if [ -n "$FAILED_IDS" ]; then
  wp wc webhook delete $FAILED_IDS --user=admin --force
  echo "Başarısız webhook'lar temizlendi."
fi

Gerçek Dünya Senaryosu 3: Webhook Sağlık Kontrolü

Production ortamında webhook’larınızın sağlıklı çalışıp çalışmadığını düzenli kontrol eden bir monitoring scripti şart. Bu scripti cron’a ekleyerek günlük raporlama yapabilirsiniz:

#!/bin/bash
# webhook-health-check.sh
# Cron: 0 9 * * * /usr/local/bin/webhook-health-check.sh

WP_PATH="/var/www/html"
ADMIN_EMAIL="[email protected]"
LOG_FILE="/var/log/webhook-health.log"

DATE=$(date '+%Y-%m-%d %H:%M:%S')
echo "=== Webhook Sağlık Kontrolü: $DATE ===" >> "$LOG_FILE"

# Tüm webhook'ları JSON olarak al
WEBHOOKS=$(wp wc webhook list 
  --path="$WP_PATH" 
  --user=admin 
  --format=json 
  --fields=id,name,status,topic,failure_count)

# Başarısız webhook'ları filtrele
FAILED=$(echo "$WEBHOOKS" | python3 -c "
import json, sys
data = json.load(sys.stdin)
failed = [w for w in data if w.get('status') == 'deliver_failed']
for w in failed:
    print(f"ID: {w['id']} | Isim: {w['name']} | Topic: {w['topic']}")
")

if [ -n "$FAILED" ]; then
  echo "UYARI - Başarısız webhook'lar bulundu:" >> "$LOG_FILE"
  echo "$FAILED" >> "$LOG_FILE"
  
  # Email bildirimi gönder
  echo -e "Aşağıdaki webhook'lar başarısız durumda:nn$FAILED" | 
    mail -s "WooCommerce Webhook Uyarısı" "$ADMIN_EMAIL"
else
  echo "Tüm webhook'lar sağlıklı." >> "$LOG_FILE"
fi

API Versiyonu ve Payload Yönetimi

Webhook’lardan gelen payload’ı doğru işlemek için hangi API versiyonunu kullandığınızı bilmeniz gerekiyor. WP-CLI ile webhook oluştururken bunu belirtebilirsiniz:

wp wc webhook create 
  --user=admin 
  --name="Modern API Webhook" 
  --topic="order.created" 
  --delivery_url="https://api.sirket.com/v3/webhook" 
  --status="active" 
  --secret="guvenli-secret-buraya" 
  --api_version="v3"

Mevcut bir webhook’un API versiyonunu güncellemek için:

wp wc webhook update 42 
  --user=admin 
  --api_version="v3"

Webhook Secret Yönetimi ve Güvenlik

Secret’ları düz metin olarak script’lere yazmak kötü bir pratik. Environment variable veya harici secret yönetim araçları kullanın:

# .env dosyasından secret okuma
source /etc/woocommerce-secrets.env

wp wc webhook create 
  --user=admin 
  --name="Guvenli Webhook" 
  --topic="order.created" 
  --delivery_url="$WEBHOOK_URL" 
  --status="active" 
  --secret="$WC_WEBHOOK_SECRET"

/etc/woocommerce-secrets.env dosyası şu şekilde görünmeli:

WC_WEBHOOK_SECRET="uzun-rastgele-guclu-bir-secret-buraya"
WEBHOOK_URL="https://api.sirket.com/webhook"

Bu dosyanın izinlerini mutlaka kısıtlayın:

chmod 600 /etc/woocommerce-secrets.env
chown www-data:www-data /etc/woocommerce-secrets.env

Webhook Delivery Log’larını İncelemek

WooCommerce webhook delivery logları doğrudan WP-CLI üzerinden erişilebilir değil, ancak veritabanından çekebilirsiniz. Alternatif olarak WooCommerce’in yerleşik log sistemini kullanabilirsiniz:

# WooCommerce loglarını görüntüle
wp wc log list --user=admin

# Belirli kayıtları filtrele
wp post list 
  --post_type=shop_webhook 
  --fields=ID,post_title,post_status 
  --format=table

Webhook delivery geçmişi için veritabanına doğrudan sorgu atmak bazen daha pratik:

wp db query "
  SELECT 
    webhook_id,
    delivery_url,
    request_method,
    response_code,
    response_message,
    date_created
  FROM wp_woocommerce_webhook_logs 
  WHERE response_code != 200
  ORDER BY date_created DESC 
  LIMIT 20;
" --user=root

Toplu Webhook Durumu Değiştirme

Maintenance window sırasında tüm webhook’ları geçici olarak durdurmak isteyebilirsiniz:

#!/bin/bash
# Tüm aktif webhook'ları duraklat
AKTIF_IDS=$(wp wc webhook list 
  --user=admin 
  --status=active 
  --field=id 
  --format=ids)

for id in $AKTIF_IDS; do
  wp wc webhook update $id --user=admin --status="paused"
  echo "Webhook $id duraklatıldı"
done

echo "Maintenance başlayabilir. Webhook ID'leri: $AKTIF_IDS"
echo "$AKTIF_IDS" > /tmp/paused-webhooks.txt

Maintenance bittikten sonra yeniden aktifleştirmek için:

# Saklanan ID'leri yeniden aktifleştir
PAUSED_IDS=$(cat /tmp/paused-webhooks.txt)

for id in $PAUSED_IDS; do
  wp wc webhook update $id --user=admin --status="active"
  echo "Webhook $id yeniden aktifleştirildi"
done

rm /tmp/paused-webhooks.txt
echo "Tüm webhook'lar yeniden aktif."

Staging ve Production Arasında Webhook Taşıma

Staging ortamında kurduğunuz webhook konfigürasyonunu production’a taşımak için şu yaklaşımı kullanabilirsiniz:

# Staging'den export
wp wc webhook list 
  --path="/var/www/staging" 
  --user=admin 
  --format=json 
  --fields=name,topic,delivery_url,status,secret,api_version 
  > /tmp/webhooks-export.json

echo "Webhook konfigürasyonları export edildi."

Sonra bu JSON’ı okuyup production’da oluşturmak için bir Python scripti ile:

python3 << 'EOF'
import json
import subprocess

with open('/tmp/webhooks-export.json', 'r') as f:
    webhooks = json.load(f)

for wh in webhooks:
    # Production URL'lerini staging URL'leriyle değiştir
    prod_url = wh['delivery_url'].replace('staging.api.', 'api.')
    
    cmd = [
        'wp', 'wc', 'webhook', 'create',
        '--path=/var/www/production',
        '--user=admin',
        f'--name={wh["name"]}',
        f'--topic={wh["topic"]}',
        f'--delivery_url={prod_url}',
        f'--status={wh["status"]}',
        f'--secret={wh.get("secret", "")}',
        f'--api_version={wh.get("api_version", "v3")}'
    ]
    
    result = subprocess.run(cmd, capture_output=True, text=True)
    print(f'{wh["name"]}: {"OK" if result.returncode == 0 else "HATA"}')
    
EOF

Yaygın Hatalar ve Çözümleri

WP-CLI ile webhook yönetiminde sık karşılaşılan sorunlar:

Yetki hatası:

# Hatalı
wp wc webhook list

# Doğru - her zaman --user belirt
wp wc webhook list --user=admin

SSL sertifika hatası: Webhook URL’niz geçersiz SSL sertifikasına sahip bir endpoint’e işaret ediyorsa WooCommerce teslimatı reddedebilir. Bunu test ortamında bypass etmek için WooCommerce ayarlarından “Enable Legacy REST API” ve ilgili SSL doğrulama ayarlarını kontrol edin.

Webhook tetiklenmiyor: Webhook status’unü kontrol edin, deliver_failed durumuna düşmüş olabilir:

wp wc webhook get 42 --user=admin --fields=status,failure_count
# Status deliver_failed ise yeniden aktifleştirin
wp wc webhook update 42 --user=admin --status=active

Büyük payload sorunları: Bazı hosting sağlayıcılar büyük POST isteklerini bloklar. Bu durumda WooCommerce webhook payload boyutunu küçülten bir filtre ekleyebilirsiniz.

Sonuç

WP-CLI ile WooCommerce webhook yönetimi, özellikle çoklu site veya otomatik deployment senaryolarında inanılmaz zaman kazandırıyor. Manuel admin paneli işlemlerini script’lere dönüştürmek, hem tekrar edilebilirlik sağlıyor hem de insan hatası riskini minimuma indiriyor.

Pratikte şu noktalara dikkat edin: secret’larınızı güçlü tutun ve environment variable’lardan okuyun, api_version olarak her zaman v3 kullanın, deliver_failed webhook’larını izleyen bir monitoring ekleyin ve maintenance window’larında toplu durdurma/başlatma script’lerinizi hazırda bulundurun.

WooCommerce ekosistemi büyüdükçe webhook entegrasyonları da karmaşıklaşıyor. Bu komutları iyi öğrenmek, sizi hem geliştirici ekiple daha iyi iletişim kuran hem de bağımsız entegrasyon sorunlarını çözebilen bir sysadmin yapıyor. Sonraki adım olarak WP-CLI’ın wp wc webhook komutlarını Ansible playbook’larınıza veya CI/CD pipeline’larınıza entegre etmeyi düşünebilirsiniz.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir