S2S Postback İleri Seviye Affiliate Setup: HMAC-SHA256 Kurulumu

İstanbul Şişli'deki performance marketing ajansı Doğa, 38 müşteri portföyünü thMenu'ya yönlendiren bir affiliate. Manuel raporlamadan S2S postback'e geçtiğinde ROI %220 arttı — çünkü her commission event'i, kendi attribution platformuna milisaniyeler içinde otomatik akmaya başladı. İşte bu altyapıyı kurmak için bilmeniz gereken her şey.

S2S Postback Nedir, Neden Gerekli?

Server-to-server (S2S) postback, affiliate'in tracking sunucusu ile thMenu'nun commission engine'i arasında doğrudan, browser'sız bir veri köprüsüdür. Pixel-based tracking'in aksine cookie kayıplarından, ad-blocker'lardan ve ITP kısıtlamalarından etkilenmez. Doğa'nın ajansı 38 restoran portföyünde aylık 1.200'den fazla commission event üretiyor — manuel CSV ile takip imkânsızdı.

thMenu Phase 3'te her commission event'i — created, refunded, released — tetiklendiğinde worker, affiliate'in kayıtlı postback URL'sine POST atar. Payload HMAC-SHA256 ile imzalanır ve X-thMenu-Signature: sha256=<hmac> header'ında taşınır. Bu sayede alıcı sunucu, payload'un gerçekten thMenu'dan geldiğini şüphesiz doğrulayabilir.

Affiliate Dashboard Üzerinden Kurulum

Kurulum üç adımda tamamlanır. Affiliate dashboard'da Settings → Postback bölümüne gidin ve şu sırayı izleyin:

1. Postback URL alanına kendi tracking endpoint'inizi yapıştırın (örn. https://track.dogaajans.com/thmenu/postback). HTTPS zorunludur. 2. Enabled toggle'ını açın; sistem otomatik olarak 64-karakterlik signing secret üretir. 3. Bu secret'ı tek seferlik kopyalayın — sayfayı yenilediğinizde bir daha gösterilmez. Vault'unuza (1Password, HashiCorp Vault) kaydedin.

Doğa'nın setup'ında secret, Vercel environment variable olarak THMENU_POSTBACK_SECRET ismiyle saklanıyor. Postback endpoint'i isteği aldığında signature'ı doğruluyor, geçerliyse event'i Postgres'e yazıyor, geçersizse 401 dönüyor.

Payload, Retry ve Doğrulama

Postback payload'u JSON formatında şu alanları içerir: event_type (created/refunded/released), affiliate_id, commission_id, restaurant_id, amount_cents, currency, timestamp ve idempotency_key. Idempotency key sayesinde aynı event tekrar geldiğinde duplicate kayıt oluşmaz — kritik bir özellik.

Başarısız POST (4xx/5xx veya timeout) durumunda thMenu cron'u 5 deneme, exponential backoff ile (1dk, 5dk, 30dk, 2sa, 12sa) tekrar dener. Tüm denemeler başarısızsa event affiliate_postback_log tablosunda "dead" olarak işaretlenir ve super-admin alert'i tetiklenir. Doğa, bu sayede iki kez DNS outage yaşadığında bile tek event kaybetmedi.

FAQ

HMAC signature'ı nasıl doğrularım? Raw request body'yi alıp signing secret ile HMAC-SHA256 hesaplayın ve X-thMenu-Signature header'ındaki sha256= prefix sonrasıyla timing-safe karşılaştırın (Node.js'te crypto.timingSafeEqual).

Secret'ı kaybedersem ne olur? Dashboard'dan postback'i disable edip tekrar enable ederek yeni secret üretebilirsiniz. Eski secret anında geçersiz olur; aktif retry kuyruğundaki event'ler yeni secret ile yeniden imzalanır.

Hangi affiliate tier'larda kullanılabilir? S2S postback Phase 3 özelliği olarak tüm aktif affiliate'lere açıktır; tier kısıtı yoktur. Ancak Silver ve üzerinde dashboard'da gelişmiş analytics (success rate, p95 latency) görürsünüz.

Faydalı buldunuz mu? Paylaşın.