Web Kancası Hata Ayıklama ve İzleme: Eksiksiz Sorun Giderme Kılavuzu

2025 Merge.dev anketi, API entegrasyon hatalarının %62'sinin webhook dağıtım sorunlarından kaynaklandığını, ancak mühendislik ekiplerinin yalnızca %23'ünün özel webhook izleme sistemine sahip olduğunu ortaya çıkardı. Web kancaları aldatıcı derecede basittir (bir sistemden diğerine bir HTTP POST'udur), ancak üretimde incelikli ve sinir bozucu şekillerde başarısız olurlar.

Bu kılavuz, web kancalarının neden başarısız olduğunu anlamaktan, güçlü hata ayıklama iş akışları oluşturmaya ve sorunları kullanıcılarınızdan önce yakalayan üretim düzeyinde izleme uygulamaya kadar tüm web kancası yaşam döngüsünü kapsar.

Temel Çıkarımlar

• Web kancaları sessizce başarısız olur — kodunuzun hata yanıtı aldığı API çağrılarının aksine, web kancası hataları gönderen tarafta meydana gelir ve sisteminiz, izleme yapmadığınız sürece isteğin denendiğini asla bilmez.
• En yaygın beş web kancası hatası şunlardır: Uç noktaya ulaşılamıyor (DNS/ağ), SSL sertifikası sorunları, zaman aşımı (işleme çok uzun sürdü), yanlış yük ayrıştırma ve imza doğrulama hatası.
• Idempotency zorunludur — web kancaları, yeniden denemeler nedeniyle birden fazla kez teslim edilebilir; bu nedenle işleyiciniz, bir veri yükünü bir kez mi yoksa on kez mi işlese aynı sonucu üretmelidir.
• HMAC-SHA256'yı kullanan imza doğrulama, web kancası güvenliği için endüstri standardıdır; üretimde asla doğrulanmamış yükleri işlemeyin.
• Yapılandırılmış günlük kaydı ve uyarı sorunları birkaç dakika içinde yakalar, geçersiz ileti kuyrukları ise hiçbir olayın kalıcı olarak kaybolmamasını sağlar.

1. Web Kancası Mimarisinin Temelleri

Hata ayıklamadan önce web kancalarının sistemlerde nasıl aktığını anlayın:

┌──────────┐     HTTP POST      ┌──────────────┐     Queue      ┌──────────────┐
│  Source   │ ──────────────────>│  Your Server │ ────────────>  │  Processor   │
│ (Stripe,  │  Headers + JSON    │  (Receiver)  │  Async job     │  (Handler)   │
│  Shopify) │                    │              │                │              │
└──────────┘                    └──────────────┘                └──────────────┘
      │                                │                               │
      │  Expects 2xx within            │  Verify signature             │  Business logic
      │  5-30 seconds                  │  Parse payload                │  Database writes
      │                                │  Enqueue for processing       │  Trigger side effects
      │  Retries on failure            │  Return 200 immediately       │  Log completion
      └────────────────────────────────┘                               └──────────────────

Kritik tasarım ilkesi: Web kancasını (dönüş 200) mümkün olduğu kadar hızlı bir şekilde onaylayın ve ardından eşzamansız olarak işleyin. Çoğu webhook göndericisinin agresif zaman aşımları vardır (5-30 saniye) ve uç noktanız zamanında yanıt vermezse yeniden deneyecektir.

2. En Yaygın Beş Web Kancası Arızası

Hata 1: Uç Noktaya Erişilemiyor

# Symptoms: Sender shows "connection refused" or "DNS resolution failed"
# Common causes:
# - Firewall blocking the sender's IP range
# - DNS misconfiguration after domain migration
# - Load balancer health check failing
# - Server crashed or not started

# Diagnostic steps:
# 1. Test connectivity from outside your network
curl -X POST https://your-domain.com/webhooks/stripe \
  -H "Content-Type: application/json" \
  -d '{"test": true}' \
  -v  # Verbose output shows connection details

# 2. Check DNS resolution
nslookup your-domain.com
dig your-domain.com +short

# 3. Check if the port is listening
nc -zv your-domain.com 443

# 4. Check firewall rules (if you have server access)
sudo ufw status
sudo iptables -L -n | grep 443

Hata 2: SSL Sertifikası Sorunları

# Symptoms: "SSL handshake failed", "certificate expired", "self-signed cert"
# Webhook senders REQUIRE valid SSL certificates

# Check certificate expiry
echo | openssl s_client -servername your-domain.com -connect your-domain.com:443 2>/dev/null | openssl x509 -noout -dates

# Check full certificate chain
openssl s_client -connect your-domain.com:443 -showcerts < /dev/null 2>/dev/null

# Common fix: renew Let's Encrypt certificate
# sudo certbot renew --force-renewal
# sudo systemctl reload nginx

Arıza 3: Zaman Aşımı

# Symptoms: Sender retries because your endpoint took too long
# Solution: Acknowledge immediately, process asynchronously

# BAD: Processing inline (may take 10+ seconds)
@app.route('/webhooks/stripe', methods=['POST'])
def bad_webhook_handler():
    event = parse_stripe_event(request)
    process_payment(event)        # Database queries, external API calls
    send_confirmation_email(event) # SMTP call
    update_inventory(event)        # More database queries
    return jsonify({'status': 'ok'}), 200  # Too late — Stripe already timed out

# GOOD: Acknowledge immediately, process in background
@app.route('/webhooks/stripe', methods=['POST'])
def good_webhook_handler():
    # Verify signature FIRST (fast)
    verify_stripe_signature(request)

    # Enqueue for background processing
    task_queue.enqueue('process_stripe_event', request.json)

    # Return 200 within milliseconds
    return jsonify({'status': 'received'}), 200

Hata 4: Yük Ayrıştırma Hataları

# Symptoms: 400/500 errors, "unexpected token", type errors
# Cause: Assumptions about payload structure that break with API updates

# BAD: Assuming structure
def process_order(payload):
    customer_email = payload['data']['object']['customer']['email']  # KeyError!

# GOOD: Defensive parsing
def process_order(payload):
    try:
        data = payload.get('data', {})
        obj = data.get('object', {})
        customer = obj.get('customer', {})

        # Customer might be a string (ID) or an object
        if isinstance(customer, str):
            customer_email = None  # Need to fetch from API
        else:
            customer_email = customer.get('email')

        if not customer_email:
            logger.warning(f"No customer email in webhook: {payload.get('id')}")
            return

    except Exception as e:
        logger.exception(f"Failed to parse webhook payload: {e}")
        raise

Hata 5: İmza Doğrulama Hatası

import hmac
import hashlib

def verify_stripe_signature(request):
    """Verify Stripe webhook signature."""
    payload = request.data  # Raw bytes, NOT parsed JSON
    sig_header = request.headers.get('Stripe-Signature', '')
    webhook_secret = os.environ['STRIPE_WEBHOOK_SECRET']

    # Parse the signature header
    elements = dict(item.split('=', 1) for item in sig_header.split(','))
    timestamp = elements.get('t')
    signature = elements.get('v1')

    if not timestamp or not signature:
        raise ValueError('Missing signature components')

    # Compute expected signature
    signed_payload = f'{timestamp}.{payload.decode("utf-8")}'
    expected = hmac.new(
        webhook_secret.encode('utf-8'),
        signed_payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError('Signature verification failed')

    # Check timestamp freshness (prevent replay attacks)
    import time
    tolerance = 300  # 5 minutes
    if abs(time.time() - int(timestamp)) > tolerance:
        raise ValueError('Webhook timestamp too old')

Yaygın imza doğrulama hataları:

• Doğrulamadan önce JSON'un ayrıştırılması (ham gövdeyi değiştirir)
• Yanlış sırrın kullanılması (test ve canlı mod)
• Sabit zamanlı karşılaştırmayı kullanmamak (hmac.compare_digest)
• İşleyiciniz görmeden önce istek gövdesini değiştiren çerçeve ara yazılımı

3. Hata Ayıklama Araçları

ngrok — Yerel Uç Noktaları Açığa Çıkarın

# Install and expose local port
ngrok http 3001

# Output:
# Forwarding https://abc123.ngrok-free.app -> http://localhost:3001
# Use this URL as your webhook endpoint in the sender's dashboard

# ngrok provides a web inspector at http://127.0.0.1:4040
# - See every request/response pair
# - Replay failed webhooks
# - Inspect headers and bodies

webhook.site — Hızlı Test

# 1. Go to https://webhook.site — get a unique URL
# 2. Configure that URL as your webhook endpoint
# 3. Trigger events and see payloads in real-time
# 4. Copy the payload format for your handler development

curl — Manuel Test

# Simulate a Stripe checkout.session.completed webhook
curl -X POST http://localhost:3001/api/billing/webhook \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1616161616,v1=abc123..." \
  -d '{
    "id": "evt_test_123",
    "type": "checkout.session.completed",
    "data": {
      "object": {
        "id": "cs_test_456",
        "customer": "cus_test_789",
        "amount_total": 4999,
        "currency": "usd",
        "metadata": {
          "product_id": "42",
          "user_id": "7"
        }
      }
    }
  }'

# Watch for the response status and body

Yapılandırılmış Günlük Kaydı

import structlog
import json
from datetime import datetime

logger = structlog.get_logger()

def log_webhook_event(request, response_status, processing_time_ms, error=None):
    """Log every webhook with full context for debugging."""
    log_data = {
        'event': 'webhook_received',
        'timestamp': datetime.utcnow().isoformat(),
        'source': detect_webhook_source(request),
        'event_type': request.json.get('type', 'unknown'),
        'event_id': request.json.get('id', 'unknown'),
        'method': request.method,
        'path': request.path,
        'content_length': request.content_length,
        'response_status': response_status,
        'processing_time_ms': processing_time_ms,
        'ip_address': request.remote_addr,
        'user_agent': request.headers.get('User-Agent', ''),
    }

    if error:
        log_data['error'] = str(error)
        log_data['error_type'] = type(error).__name__
        logger.error('webhook_failed', **log_data)
    else:
        logger.info('webhook_processed', **log_data)

4. Stratejileri Yeniden Deneyin

Web kancası gönderenlerin çoğu, üstel gerilemeyle otomatik yeniden denemeler uygular. Stripe 24 saat içinde en fazla 3 kez yeniden dener. Shopify 48 saat içinde 19 defaya kadar yeniden deneme yapar. Sisteminiz, özdeşlik anahtarları aracılığıyla yinelenen teslimatları işleyecek şekilde tasarlanmalı ve veritabanı zaman aşımları gibi geçici hataların etkinlikleri kalıcı olarak kaybetmemesi için hataları işlemek için kendi yeniden deneme sıranızı uygulamanız gerekir.

Gönderen Yeniden Deneme Politikaları

Kendi Yeniden Deneme Sıranızı Oluşturma

// Node.js retry queue with exponential backoff
const Bull = require('bull');

const webhookQueue = new Bull('webhooks', {
  redis: { host: 'localhost', port: 6379 },
  defaultJobOptions: {
    attempts: 5,
    backoff: {
      type: 'exponential',
      delay: 2000, // 2s, 4s, 8s, 16s, 32s
    },
    removeOnComplete: 100,
    removeOnFail: false, // Keep failed jobs for analysis
  },
});

// Producer: enqueue webhook for processing
async function enqueueWebhook(eventType, payload, source) {
  await webhookQueue.add(eventType, {
    payload,
    source,
    receivedAt: new Date().toISOString(),
    idempotencyKey: payload.id || `${source}-${Date.now()}`,
  });
}

// Consumer: process webhooks
webhookQueue.process('checkout.session.completed', async (job) => {
  const { payload, idempotencyKey } = job.data;

  // Check idempotency
  const processed = await redis.get(`webhook:${idempotencyKey}`);
  if (processed) {
    console.log(`Skipping duplicate webhook: ${idempotencyKey}`);
    return { status: 'duplicate', key: idempotencyKey };
  }

  try {
    // Process the event
    await handleCheckoutCompleted(payload);

    // Mark as processed (TTL 48h)
    await redis.setex(`webhook:${idempotencyKey}`, 172800, 'processed');

    return { status: 'success' };
  } catch (error) {
    // Will be retried automatically by Bull
    throw error;
  }
});

// Dead letter handler
webhookQueue.on('failed', (job, error) => {
  if (job.attemptsMade >= job.opts.attempts) {
    console.error(`Webhook permanently failed after ${job.attemptsMade} attempts:`, {
      eventType: job.name,
      idempotencyKey: job.data.idempotencyKey,
      error: error.message,
    });
    // Send alert to Slack/PagerDuty
    alertService.sendCritical('Webhook permanently failed', {
      job: job.id,
      event: job.name,
      error: error.message,
    });
  }
});

5. Bağımsızlık Uygulaması

import hashlib
import redis

redis_client = redis.Redis(host='localhost', port=6379, db=0)

def process_webhook_idempotently(event_id, event_type, payload, handler_fn):
    """Ensure a webhook is processed exactly once."""
    # Create idempotency key
    idem_key = f"webhook:processed:{event_id}"

    # Check if already processed (atomic operation)
    if redis_client.exists(idem_key):
        logger.info(f"Skipping duplicate webhook: {event_id}")
        return {'status': 'duplicate'}

    # Set a processing lock (prevents concurrent processing)
    lock_key = f"webhook:lock:{event_id}"
    lock_acquired = redis_client.set(lock_key, '1', nx=True, ex=60)

    if not lock_acquired:
        logger.warning(f"Webhook already being processed: {event_id}")
        return {'status': 'in_progress'}

    try:
        # Process the event
        result = handler_fn(event_type, payload)

        # Mark as processed (keep for 48 hours)
        redis_client.setex(idem_key, 172800, json.dumps({
            'processed_at': datetime.utcnow().isoformat(),
            'result': str(result),
        }))

        return {'status': 'processed', 'result': result}

    except Exception as e:
        # Release lock so it can be retried
        redis_client.delete(lock_key)
        raise

    finally:
        redis_client.delete(lock_key)

6. Kontrol Panelini İzleme

İzlenecek Temel Metrikler

Prometheus Metrik Örneği

from prometheus_client import Counter, Histogram, Gauge

# Counters
webhook_received_total = Counter(
    'webhook_received_total',
    'Total webhooks received',
    ['source', 'event_type']
)

webhook_processed_total = Counter(
    'webhook_processed_total',
    'Total webhooks successfully processed',
    ['source', 'event_type']
)

webhook_failed_total = Counter(
    'webhook_failed_total',
    'Total webhook processing failures',
    ['source', 'event_type', 'error_type']
)

webhook_duplicate_total = Counter(
    'webhook_duplicate_total',
    'Duplicate webhook deliveries skipped',
    ['source']
)

# Histograms
webhook_processing_duration = Histogram(
    'webhook_processing_duration_seconds',
    'Time to process a webhook',
    ['source', 'event_type'],
    buckets=[0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0]
)

# Gauges
webhook_queue_depth = Gauge(
    'webhook_queue_depth',
    'Current number of webhooks waiting to be processed',
    ['source']
)

Durum Kontrolü Uç Noktası

// NestJS health check example
@Controller('health')
export class HealthController {
  @Get('webhooks')
  async webhookHealth() {
    const stats = await this.webhookService.getStats();

    const healthy = stats.failureRate < 0.02
      && stats.queueDepth < 500
      && stats.avgProcessingTimeMs < 2000
      && stats.deadLetterCount < 10;

    return {
      status: healthy ? 'healthy' : 'degraded',
      metrics: {
        totalReceived24h: stats.totalReceived,
        successRate: `${((1 - stats.failureRate) * 100).toFixed(2)}%`,
        avgProcessingTimeMs: stats.avgProcessingTimeMs,
        queueDepth: stats.queueDepth,
        deadLetterCount: stats.deadLetterCount,
        duplicateRate: `${(stats.duplicateRate * 100).toFixed(2)}%`,
        lastReceivedAt: stats.lastReceivedAt,
      },
    };
  }
}

7. En İyi Güvenlik Uygulamaları

IP Beyaz Listesine Ekleme

# Nginx configuration for webhook endpoints
location /api/webhooks/stripe {
    # Only allow Stripe's IP ranges
    # https://stripe.com/docs/ips
    allow 3.18.12.63;
    allow 3.130.192.0/24;
    allow 13.235.14.0/24;
    allow 18.211.135.0/24;
    allow 35.154.171.0/24;
    deny all;

    proxy_pass http://localhost:3001;
}

Doğrulama Kontrol Listesi İste

1. Şifreleme imzasını doğrulayın (HMAC-SHA256)
2. Zaman damgasının tolerans dahilinde olup olmadığını kontrol edin (5 dakika)
3. Content-Type başlığını doğrulayın
4. Yük boyutunun sınırlar dahilinde olup olmadığını kontrol edin (reddet > 1 MB)
5. Beklenen etkinlik türünün doğrulanması
6. Gönderen aralıkları yayınlıyorsa IP adresini doğrulayın
7. Uç noktayı oran sınırı (kötüye kullanımı önleyin)

def validate_webhook_request(request):
    """Comprehensive webhook request validation."""
    errors = []

    # 1. Content-Type
    if request.content_type != 'application/json':
        errors.append(f'Invalid Content-Type: {request.content_type}')

    # 2. Payload size (max 1MB)
    if request.content_length and request.content_length > 1_048_576:
        errors.append(f'Payload too large: {request.content_length} bytes')

    # 3. Required headers
    if not request.headers.get('X-Webhook-Signature'):
        errors.append('Missing signature header')

    # 4. Valid JSON
    try:
        payload = request.json
    except Exception:
        errors.append('Invalid JSON payload')
        return errors

    # 5. Required fields
    if 'type' not in payload:
        errors.append('Missing event type')
    if 'id' not in payload:
        errors.append('Missing event ID')

    return errors

8. Hata Ayıklama Kontrol Listesi

Bir web kancası çalışmayı bıraktığında şu sistematik yaklaşımı izleyin:

1. Gönderenin kontrol panelini kontrol edin — Çoğu platform (Stripe, Shopify, GitHub) teslimat girişimlerini, yanıt kodlarını ve zaman damgalarını gösterir
2. Sunucu günlüklerinizi kontrol edin — Nginx/Apache'de webhook uç noktası erişim günlüklerini arayın
3. SSL sertifikasını doğrulayın — Süresi dolmuş sertifikalar bir numaralı sessiz katildir
4. Curl ile test edin — Farklı bir ağdan uç noktanıza manuel olarak POST yapın
5. DNS çözümlemesini kontrol edin — Alanınızın harici ağlardan doğru şekilde çözümlendiğinden emin olun
6. Webhook sırrını doğrulayın — Temel değişiklikler veya ortam geçişleri sırasında sırlar dönüşümlü olarak kullanılır
7. Veri yükü biçimi değişikliklerini kontrol edin — API sürümü güncellemeleri webhook verilerini değiştirebilir
8. Son dağıtımları inceleyin — Kod değişiklikleri işleyiciyi bozmuş olabilir
9. Kaynak sınırlarını kontrol edin — Bellek, CPU, veritabanı bağlantıları
10. Tüm işlem hattını test edin — Veritabanı yazma işlemlerini, kuyruk işlemeyi ve yan etkileri doğrulayın

Sıkça Sorulan Sorular

Yerel geliştirmede web kancalarını nasıl test ederim?

Yerel sunucunuzu internete açmak için ngrok veya benzer bir tünel aracı kullanın. Localhost:3001'e yönlendiren genel bir URL almak için 'ngrok http 3001'i çalıştırın. Bu URL'yi gönderenin kontrol panelinde web kancası uç noktası olarak yapılandırın. Localhost:4040'taki ngrok web denetçisi her isteği incelemenize ve başarısız teslimatları yeniden yürütmenize olanak tanır. CI/CD için bunun yerine sahte sunucuları veya kayıt yeniden oynatma modellerini kullanın.

Webhook uç noktam neyi döndürmeli?

200 durum kodunu mümkün olan en kısa sürede, 2-5 saniye içinde döndürün. Yanıt gövdesi genellikle gönderen tarafından göz ardı edilir, ancak {"status":"received"} gibi basit bir JSON iyi bir uygulamadır. Olayı eşzamansız olarak işlemeyi planlasanız bile 200 değerini döndürün. Yalnızca imza geçersizse veya yük hatalı biçimlendirilmişse 4xx'i döndürün. İş mantığı hataları için asla 5xx döndürmeyin; bunun yerine bunları günlüğe kaydedin ve yeniden deneme kuyruğunda işleyin.

Düzensiz gelen webhook etkinliklerini nasıl ele alırım?

Yeniden denemeler ve ağ koşulları nedeniyle etkinlikler hatalı sonuçlanabilir. İşleyicinize bir zaman damgası veya sıra numarası kontrolü ekleyin. Stripe için etkinliğin oluşturulan zaman damgasını kullanın. Shopify için güncellendi_at alanını kontrol edin. Sisteminizin henüz görmediği bir duruma atıfta bulunan bir olay gelirse, daha sonra işlenmek üzere sıraya koyun veya uzlaştırmak için mevcut durumu gönderenin API'sinden alın. Kimlik anahtarları, sıra ne olursa olsun yinelenen işlemleri önler.

Webhook güvenilirliğini izlemenin en iyi yolu nedir?

Dört temel ölçümü izleyin: teslimat başarı oranı (hedef %99,5'in üzerinde), ortalama işlem süresi (hedef 500 milisaniyenin altında), kuyruk derinliği (hedef 100'ün altında) ve geçersiz kuyruk boyutu (hedef sıfır). Herhangi bir ölçüm eşiğini aştığında uyarılar ayarlayın. Kontrol panelleri için Prometheus'u Grafana ile veya Datadog ya da New Relic gibi yönetilen bir hizmetle kullanın. Ayrıca, kendi günlüklerinizde göremeyebileceğiniz teslimat hatalarına karşı gönderenin webhook kontrol panelini de izleyin.

Webhook yeniden oynatma saldırılarını nasıl önlerim?

Üç savunma uygulayın: İlk olarak, HMAC-SHA256'yı paylaşılan bir sırla kullanarak her istekteki şifreleme imzasını doğrulayın. İkinci olarak, imzalı yükteki zaman damgasını kontrol edin ve 5 dakikadan eski olayları reddedin (Stripe bunu imza şemasına dahil eder). Üçüncüsü, saldırgan geçerli bir imzalı isteği zaman damgası penceresi içinde yeniden oynatsa bile her etkinliğin tam olarak bir kez işlenmesini sağlamak için eş güç anahtarlarını kullanın.

Sonraki Adımlar

Webhook güvenilirliği olay odaklı entegrasyonların temelidir. Bu kılavuzdaki modeller (imza doğrulama, bağımsız işlem, eşzamansız kuyruklar, yapılandırılmış izleme) hangi platformları entegre ettiğinize bakılmaksızın geçerlidir.

İlgili kaynaklar:

• Odoo REST API Eğitimi — Odoo ile API entegrasyonu
• ECOSIRE Marketplace Bağlayıcıları — Önceden oluşturulmuş Odoo entegrasyonları
• E-ticaret 2026 için En İyi ERP — Entegrasyona hazır ERP karşılaştırması

ECOSIRE, Odoo, Shopify, Stripe ve düzinelerce başka platformu birbirine bağlayan üretim düzeyinde webhook entegrasyonları oluşturur. Entegrasyon hizmetlerimiz izleme kontrol panellerini, teslim edilmeyen mektup kuyruğu yönetimini ve %99,9 teslimat garantisini içerir. Entegrasyon mühendislerimizle konuşun.