Webhook’lar Çalışmıyor (Twitter/X): CRC, Gizli Anahtar ve İmzayı Doğrulama

Bir sabah uygulamamın loglarına bakarken gözlerime inanamadım. Twitter’dan webhook çağrıları bekliyordum ama sistem bomboştu. 🚨 “Acaba kullanıcı yok mu?” diye düşündüm, ama sorun bende değilmiş: Webhook kurulumum başarısız olmuştu. Özellikle CRC (Challenge-Response Check) ve imza doğrulama aşamalarında hata yapmışım.

Eğer sen de Twitter/X API’siyle çalışan bir uygulama geliştiriyorsan ve webhook’ların çalışmadığını görüyorsan, panik yapma. Çünkü bu sorun çok yaygın ve çoğu zaman basit bir ayar veya imza kontrolü ile çözülüyor.

Webhook Nedir ve Neden Önemli?

Webhook, Twitter’ın sisteminde gerçekleşen bir olayı (örneğin mention, DM veya takip) senin uygulamana anlık olarak iletmesini sağlar. Yani sen sürekli API çağrısı yapıp “Yeni bir şey oldu mu?” diye sormazsın. Twitter sana haber verir. 📩

Resmi Twitter Developer belgelerinde webhook güvenliğinin üç temel ayağı olduğu belirtiliyor:

1. CRC (Challenge-Response Check): Webhook’un gerçekten senin kontrolünde olduğunu doğrulamak.
2. Gizli Anahtar (Consumer Secret): İmzalama işlemlerinde kullanılan anahtar.
3. İmza Doğrulama: Twitter’dan gelen isteğin gerçekten Twitter’a ait olup olmadığını kontrol etmek.

Sorun 1: CRC (Challenge-Response Check)

Webhook kaydı yapılırken Twitter senin endpoint’ine bir CRC isteği gönderir. Bu isteğe doğru yanıt vermezsen webhook aktif olmaz.

Nasıl Çalışır?

• Twitter sana bir crc_token gönderir.
• Sen bu token’ı gizli anahtarın ile HMAC-SHA256 algoritması kullanarak imzalarsın.
• Yanıt olarak response_token gönderirsin.

Twitter dokümantasyonu, CRC’nin zorunlu olduğunu vurguluyor.

Yaygın Hata: CRC isteğini sadece “200 OK” ile yanıtlamak. Bu durumda webhook doğrulanmaz.

Sorun 2: Gizli Anahtar (Consumer Secret)

CRC yanıtını üretmek için Twitter uygulamanın Consumer Secret değerine ihtiyacın var. Ama dikkat:

• Yanlış anahtar kullanırsan imza uyuşmaz.
• Anahtarı açıkta loglarsan güvenlik riski oluşur.

Benim ilk hatam tam da buydu. Yanlış projeye ait Consumer Secret ile imzalama yapıyordum. Sonuç: CRC başarısız. 🤦

Sorun 3: İmza Doğrulama

Webhook’un çalışmaya başlaması için sadece CRC yeterli değil. Her gelen istekte, Twitter HTTP header’ına bir imza (x-twitter-webhooks-signature) ekler.

Senin yapman gereken:

1. Gövdeyi al.
2. Consumer Secret ile HMAC-SHA256 hash üret.
3. Twitter’ın gönderdiği imza ile karşılaştır.

Eğer eşleşmezse isteği reddetmelisin. Bu, saldırganların sahte webhook çağrısı yapmasını önler.

Tablo: Yaygın Webhook Sorunları ve Çözümleri

Diyagram: Webhook Güvenlik Akışı

[Twitter CRC İsteği] 
        ↓ 
[Uygulama HMAC ile Yanıt Üretir] 
        ↓ 
[Webhook Aktifleşir] 
        ↓ 
[Twitter Olay Gönderir] 
        ↓ 
[İmza Doğrulama Yapılır] 
        ↓ 
[Geçerli → İşle / Geçersiz → Reddet]

Adım Adım Sorun Çözme Rehberi

1. Logları Kontrol Et: CRC isteği geliyor mu?
2. CRC Yanıtını Doğrula: response_token=sha256=... formatında mı?
3. Anahtarını Doğru Kullan: Doğru app’in Consumer Secret’ı olduğundan emin ol.
4. İmza Karşılaştırması Yap: Her POST isteğinde header imzasını doğrula.
5. HTTPS Kullan: HTTP endpoint’leri Twitter reddeder.
6. Performansı Test Et: Timeout olmaması için webhook yanıtlarını optimize et.

Örnek: “CRC Testi”

Ben CRC sürecinde sürekli hata alıyordum. Meğer yanıtı şu şekilde döndürmem gerekiyormuş:

{
  "response_token": "sha256=abcdef123456..."
}

Ben sadece token’ı düz string olarak döndürüyordum. O yüzden Twitter “Invalid response” diyordu. Doğru formatı uygulayınca sorun çözüldü. 🎉

Pro İpuçları 🚀

• Ngrok ile test yap: Localhost webhook’unu dış dünyaya açabilirsin.
• Hata loglarını kaydet: CRC yanıtlarını debug için sakla.
• İmza doğrulamayı atlama: Güvenlik açıklarına davetiye çıkarırsın.
• Timeout’ları önle: Webhook yanıtlarını minimal tut, işleme asenkron devam et.
• Birden fazla ortam ekle: Staging ve production için ayrı webhook URL’leri tanımla.

Kişisel Anekdot: “Yanlış Anahtar Kabusu”

İlk kez webhook kurarken saatlerce “Neden olmuyor?” diye düşündüm. Kod defalarca doğru görünüyordu. En sonunda fark ettim ki, Consumer Secret yerine API Key kullanmışım. 🤯 O günden sonra belgelerin altını çizmeye başladım: Anahtar =/= Secret.

Sonuç: Webhook’lar Çalıştırılabilir!

Webhook kurulumunda CRC, gizli anahtar ve imza doğrulama adımlarını doğru yapmazsan sistem çalışmaz. Ama mantığı kavrayınca süreç net:

• CRC → Kurulumu doğrular,
• Gizli anahtar → İmzalama için gereklidir,
• İmza doğrulama → Güvenliği sağlar.

Doğru yapılandırma ile webhook’ların sorunsuz çalışır ve uygulaman Twitter’dan gelen olayları anlık olarak yakalar. 🚀