Async Sonuçları Otomatik Alın
Webhook'lar, async işlemlerin sonuçlarını otomatik olarak sunucunuza iletir. Polling yerine webhook kullanarak gerçek zamanlı bildirimler alın.
import hmacimport hashlibfrom flask import Flask, request, jsonifyapp = Flask(__name__)WEBHOOK_SECRET = "your_webhook_secret"def verify_signature(body: bytes, signature: str) -> bool: expected = hmac.new( WEBHOOK_SECRET.encode(), body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)@app.post("/webhook")def handle_webhook(): signature = request.headers.get("X-Webhook-Signature", "") if not verify_signature(request.get_data(), signature): return jsonify({"error": "Invalid signature"}), 401 payload = request.get_json() if payload["event"] == "job.completed": print(f"Job {payload['job_id']} completed!") print(f"Result: {payload['result']}") elif payload["event"] == "job.failed": print(f"Job {payload['job_id']} failed: {payload.get('error')}") return jsonify({"received": True}), 200Webhook, bir olay gerçekleştiğinde sunucunuza HTTP POST isteği gönderen bir bildirim mekanizmasıdır. ProxyTurk'te async bir iş (scrape, parse, serp) tamamlandığında veya başarısız olduğunda belirttiğiniz URL'ye sonuç gönderilir.
Avantajları: - Polling'e gerek yok (daha az istek, daha az kaynak kullanımı) - Gerçek zamanlı bildirim (iş bitince anında sonuç) - Fire-and-forget pattern (isteği gönder, sonucu webhook'tan al)
İki yöntemle webhook kullanabilirsiniz:
1. İstek bazlı: Her API isteğinde webhook_url parametresi gönderin 2. Dashboard: Genel webhook URL'si tanımlayın (tüm async işler için)
Webhook URL'niz HTTPS olmalı ve dışarıdan erişilebilir olmalıdır. Localhost çalışmaz (geliştirme için ngrok veya similar tunnel kullanın).
İki event tipi mevcuttur:
- job.completed: İş başarıyla tamamlandığında. Payload'da result alanı dolu gelir. - job.failed: İş başarısız olduğunda. Payload'da error alanı hata detayını içerir.
Webhook POST isteğinin body'si JSON formatındadır:
{ "event": "job.completed", "job_id": "job_abc123", "status": "completed", "endpoint": "scrape", "result": { ... }, "meta": { "processing_time_ms": 823, "credits_used": 1, "created_at": "2026-08-12T15:30:00Z", "completed_at": "2026-08-12T15:30:01Z" } }
Header'lar: - Content-Type: application/json - X-Webhook-Signature: sha256=<HMAC-SHA256 signature> - X-Webhook-ID: Benzersiz delivery ID (idempotency için)
Her webhook isteği X-Webhook-Signature header'ı ile imzalanır. Bu imzayı doğrulayarak isteğin gerçekten ProxyTurk'ten geldiğinden emin olun.
İmza formatı: sha256=<hex-encoded HMAC-SHA256> Key: Dashboard'daki webhook secret Message: Request body (raw bytes)
Webhook teslimi başarısız olursa (HTTP 2xx dışı yanıt veya timeout) exponential backoff ile tekrar denenir:
- 1. deneme: Hemen - 2. deneme: 30 saniye sonra - 3. deneme: 2 dakika sonra - 4. deneme: 10 dakika sonra - 5. deneme: 1 saat sonra
Toplam 5 deneme yapılır. Tümü başarısız olursa webhook terk edilir. Sonuca GET /v1/jobs/{id} ile her zaman ulaşabilirsiniz.
Webhook gelmiyor: - URL'nizin HTTPS ve dışarıdan erişilebilir olduğundan emin olun - Firewall ayarlarınızı kontrol edin - Dashboard'daki webhook loglarını inceleyin
Signature doğrulanamıyor: - Raw body kullanın (parse edilmemiş JSON) - Webhook secret'ı doğru kullandığınızdan emin olun - Encoding sorunu: UTF-8 kullanın
Aynı webhook birden fazla geliyor: - X-Webhook-ID header'ını kullanarak idempotency sağlayın - İşlenen webhook ID'lerini veritabanında saklayın
Webhook hakkında sorular
Hayır, webhook URL'niz internet üzerinden erişilebilir olmalıdır. Geliştirme ortamında ngrok, localtunnel veya Cloudflare Tunnel kullanabilirsiniz.
Sunucunuzun 30 saniye içinde HTTP 2xx yanıtı dönmesi gerekir. Aksi halde timeout olarak kabul edilir ve retry yapılır.
webhook.site veya requestbin.com ile gelen webhook'ları gerçek zamanlı görebilirsiniz. Geliştirmede ngrok ile localhost'unuzu dışarı açabilirsiniz.