Webhook İmzalamak: Alıcı Tarafın Gerçekten Güvenebilmesi İçin

Webhook göndermek kolay, ama sahte webhook göndermek de aynı derecede kolay. URL'ni bilen herkes senin alıcı endpoint'ine POST atabilir. burada imzalama devreye giriyor.

Byteforge'un bu yazısında anlatıldığı gibi, sistem şu şekilde çalışıyor: Gönderici her webhook'a bir başlık ekler, örneğin `X-CompanyName-Signature: t=1234567890,v1=abc123...`. Bu başlıkta iki kritik bilgi var.

İlk olarak `t`, mesajın gönderildiği Unix timestamp'i içeriyor. Bu sayede alıcı eski mesajları reddedebiliyor, belki 5 dakikadan eski bir webhook'u kabul etmiyor. İkinci kısım `v1` ise timestamp ve ham body'nin HMAC-SHA256 hash'i. Gönderici kendi secret key'i kullanarak bu hash'i hesaplıyor:

1def _digest(secret: str, raw_body: bytes, timestamp: int) -> str:
2message = f"{timestamp}.{raw_body.decode()}".encode()
3return hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()

Alıcı taraf aynı secret key'i biliyorsa, gelen webhook'un timestamp'i ve body'sinden aynı hash'i hesaplayabilir. Eğer hash'ler eşleşirse, mesaj gerçekten senin tarafından gönderilmiş demektir, hiç kimse tarafından değiştirilmemiş.

Bu yöntemin güzelliği basitliğinde. Ekstra veritabanı sorgusuna, session yönetimine ya da karmaşık token sistemine gerek yok. Sadece HMAC ve timestamp. Webhook alıcılarının hepsinin yapması gereken şey, gelen başlığı doğrulamak ve timestamp'i kontrol etmek. Eski ya da geçersiz imzalı istekler direkt reddediliyor.

Eğer webhook'larla çalışıyorsan ve henüz imzalama yapmıyorsan, bu basit ama etkili yöntemi hemen uygula. Siber güvenlik açısından bakıldığında, bu tür doğrulama mekanizmaları API'lerin temel savunmasıdır.