Webhook imza uyumsuzlugunu raw body, secret ve HMAC katmanlarina ayir.
Webhook signature mismatch hatasi genelde tek bir sebepten cikmaz. Ham body'nin degismesi, secret'in yanlis encoding ile okunmasi, header prefix'i veya signed timestamp toleransi ayni hata mesajina donusebilir. Bu guide, Hash / HMAC araci etrafinda en kisa debug akisina odaklanir.
4 adimli webhook verify triage
-
1. Ham body'yi oldugu gibi ayir
Webhook saglayicilari cogu zaman imzayi parse edilmis obje uzerinden degil, gelen raw request body uzerinden hesaplar. Pretty print, bosluk temizligi veya key sirasi degisimi ayni event icin farkli HMAC uretir.
-
2. Signature header formatini parcala
Bazi sistemler `sha256=...`, bazilari `t=...,v1=...` veya birden fazla versiyon gonderir. Header icindeki prefix, timestamp ve digest parcasi ayrilmadan yalnizca tek bir hex degerle karsilastirma yapmak yanlis negatif verir.
-
3. Secret ve message encoding secimini eslestir
Hash / HMAC aracinda key icin utf8, hex veya base64; message icin utf8, hex veya base64 secimi ayri ayarlanir. Uretici taraf hangi encoding ile calisiyorsa ayni kombinasyon debug tarafinda da korunmalidir.
-
4. Timestamp toleransi varsa ayri test et
Stripe benzeri saglayicilarda replay korumasi icin timestamp da signed string'e dahil olabilir. Bu durumda dogru HMAC uretilse bile eski timestamp veya clock drift sebebiyle verify yine reddedilebilir.
En sik 3 mismatch sebebi
Framework body parser'i veya debug icin yapilan pretty print, gelen byte siralamasini degistirebilir. Sign edilecek veri her zaman ham request body olmalidir.
Environment degiskeni base64 saklaniyorsa ama debug tarafinda utf8 gibi kullaniliyorsa ayni body icin bambaska digest uretilir.
`sha256=` prefix'ini, `v1` alanini veya timestamp tolerance kontrolunu yok saymak verify sonucunu eksik yorumlatir.
Webhook signature okurken mini checklist
X-Signature: sha256=9c4a...
X-Timestamp: 1716207000
{"event":"invoice.paid","id":"evt_42"}- Body tam olarak gelen raw byte dizisi mi?
- Header icinde prefix veya version parcasi var mi?
- Secret utf8 mi, hex mi, base64 mu saklaniyor?
- Timestamp toleransi veya clock drift var mi?
Bu use-case'te hangi araci ne zaman acarsin?
HMAC algorithm, key encoding, message encoding ve hex/base64 ciktiyi izole test etmek icin ana arac.
Body'yi okumak icin yardimci olur; fakat imza hesaplarken reformatted JSON yerine raw body kullanmaniz gerekir.
Signed timestamp veya replay tolerance kontrolunu insan okunur tarihe cevirir.
Webhook body'nin parse ve encode katmanlarini daha genis request hazirlama akisinda toparlar.
Sik sorulanlar
JSON Formatter ile duzelttigim body'yi imza icin kullanabilir miyim?
Genelde hayir. Debug icin okunur hale getirebilirsiniz ama verify icin imzalanan tam ham body'yi korumaniz gerekir.
HMAC sonucu neden provider ile farkli gorunuyor?
Algoritma, secret encoding, message encoding veya cikis formati farkli olabilir. Ayrica provider header icinde prefix ya da version etiketi kullaniyor olabilir.
Timestamp kontrolu neden signature guide icinde?
Cunku bazi verify akislari HMAC esit olsa bile eski timestamp sebebiyle request'i reddeder. Replay korumasi imza sonucundan ayri bir katmandir.
Webhook verify akisini simdi dene
Rehberdeki kontrol noktalarini ayni request uzerinde denemek, webhook mismatch'ini satir satir log okumaktan daha hizli cozer. Once raw body'yi ayir, sonra header ve secret encoding'i Hash / HMAC ile dogrula.