Hata ayıklama
İstek gelmiyor, imza tutmuyor, zaman aşımı alıyorum — belirtiden çözüme.
İlk bakılacak yer her zaman aynı: panelde abonelik satırından Teslimat geçmişi. Orada isteğin gerçekten gönderilip gönderilmediğini, sunucunuzun ne döndüğünü ve hata sınıfını görürsünüz.
flowchart TD
A["Sorun var"] --> B{"Teslimat geçmişinde<br/>kayıt görünüyor mu?"}
B -->|"hayır"| C["Event hiç üretilmedi<br/>veya abonelik dinlemiyor"]
B -->|"evet"| D{"Durum ne?"}
D -->|"delivered"| E["İstek ulaştı, 2xx aldı.<br/>Sorun sizin işleme mantığınızda."]
D -->|"timeout"| F["Yanıt 5 sn içinde dönmedi"]
D -->|"dns / tls / connection"| G["Adrese ulaşılamıyor"]
D -->|"http_4xx"| H["Sunucunuz reddetti"]
D -->|"http_5xx"| I["Sunucunuzda hata"]
D -->|"blocked_*"| J["Adres güvenlik kontrolünden geçmedi"]
Hiç istek gelmiyor
İmza doğrulanamıyor
En sık karşılaşılan sorun. Sırayla eleyin:
Ham gövdeyi mi kullanıyorsunuz?
JSON.parse → JSON.stringify döngüsünden geçmiş bir gövdeyle imza asla
tutmaz. Framework'ünüzün ham gövde yöntemini kullanın:
| Framework | Yöntem |
|---|---|
| Express | express.raw({ type: 'application/json' }) |
| Fastify | addContentTypeParser ile buffer saklamak |
| NestJS | NestFactory.create(AppModule, { rawBody: true }) |
| Next.js | await request.text() |
Hızlı test: gelen ham gövdenin uzunluğunu loglayın, Content-Length başlığıyla
karşılaştırın. Eşit değilse ham gövdeyi almıyorsunuz.
console.log('raw:', Buffer.byteLength(rawBody), 'header:', req.get('Content-Length'));Formül doğru mu?
HMAC_SHA256(secret, timestamp + "." + rawBody)Kontrol edin:
- Nokta ayracı var mı
- Sıra doğru mu (timestamp önce)
- Çıktı hex mi (base64 değil)
- Hex küçük harf mi
Secret doğru mu?
whsec_ön eki dâhil mi? Ön ek secret'ın parçasıdır.- Baştan/sondan boşluk veya satır sonu kaçmış olabilir:
SECRET.trim()ile test edin. - Secret'ı yenilediyseniz sunucudaki değeri güncellediniz mi? Yenileme anında eskisini geçersiz kılar.
- Birden fazla aboneliğiniz varsa doğru aboneliğin secret'ını mı kullanıyorsunuz? Her aboneliğin ayrı secret'ı var.
Fingerprint karşılaştırması: panelde gördüğünüz son 4 karakter
(whsec_…92be) elinizdekiyle aynı mı?
Sunucu saati doğru mu?
Zaman damgası penceresi kontrolü sunucunuzun saatine bağlı. NTP kapalıysa geçerli istekler bile reddedilir.
timedatectl status # Linux
sntp -sS time.apple.com # macOSSystem clock synchronized: yes görmelisiniz.
Ara katman gövdeyi değiştiriyor mu?
Nginx, Cloudflare, bir API gateway ya da bir WAF gövdeyi yeniden yazıyor olabilir (gzip açma, karakter kodlaması dönüştürme, JSON güzelleştirme).
Test: isteği tünel üzerinden doğrudan uygulamanıza yönlendirin. Orada çalışıyorsa sorun ara katmandadır.
timeout alıyorum
Yanıt 5 saniyede dönmedi.
| Sebep | Çözüm |
|---|---|
| Yanıttan önce iş yapıyorsunuz | Doğrulayın, kuyruğa yazın, 200 dönün; işi worker'da yapın |
| Veritabanı sorgusu yavaş | Yanıt yolunda sorgu olmasın; en fazla bir INSERT |
| Soğuk başlatma (serverless) | Sürekli çalışan bir sunucu kullanın ya da fonksiyonu sıcak tutun |
| Sunucu yük altında | Ölçekleyin; teslimatlar 72 saat boyunca yeniden denenir ama abonelik failinge düşebilir |
Ölçün:
curl -w "\nsüre: %{time_total}s\n" -o /dev/null -s \
-X POST https://sunucunuz.com/hikie/webhook \
-H "Content-Type: application/json" --data-raw '{}'dns, tls, connection hataları
http_4xx — sunucunuz reddediyor
| Kod | Muhtemel sebep |
|---|---|
400 | İmza doğrulamanız reddediyor, ya da gövde çözümlemeniz hata veriyor |
401 / 403 | WAF/güvenlik duvarı engelliyor, ya da endpoint'iniz hikie'nin gönderemeyeceği bir kimlik doğrulaması bekliyor |
404 | Abonelikteki yol yanlış, ya da rota tanımlı değil |
405 | Rota POST kabul etmiyor |
413 | Gövde boyutu sınırınız çok düşük — büyük sepetli siparişlerde olur |
415 | application/json içerik tipini kabul etmiyorsunuz |
401 ve 403 kalıcı hata sayılır: iki ardışık teslimatta abonelik
failing durumuna düşer. Geçici bir sorunda 503 dönün.
blocked_* — adres reddedildi
Adres güvenlik kontrolünden geçmedi; istek hiç gönderilmedi.
| Hata sınıfı | Sebep |
|---|---|
blocked_scheme_not_allowed | https:// değil |
blocked_credentials_in_url | URL içinde kullanıcı adı/şifre var |
blocked_loopback_address | localhost veya 127.x.x.x |
blocked_private_address | Özel ağ adresi, .internal veya .local |
blocked_link_local_address | 169.254.x.x |
blocked_reserved_address | Ayrılmış IP aralığı |
blocked_invalid_url | URL çözümlenemedi |
Çözüm: herkese açık bir HTTPS adresi kullanın. Yerelde geliştiriyorsanız tünel açın.
delivered ama iş olmadı
Teslimat başarılı, sorun sizin tarafınızda:
Destek isterken
Şunları hazır bulundurmak süreci kısaltır:
- Aboneliğin adı veya URL'si
- Sorunlu teslimatın
Hikie-Webhook-Iddeğeri (wh_…) - Teslimat geçmişindeki durum kodu ve hata sınıfı
- Yaklaşık zaman aralığı
- Kendi sunucu loglarınızdaki karşılık gelen kayıt
Secret'ınızı hiçbir zaman destek talebine, ekran görüntüsüne veya loglara eklemeyin. Sızdığını düşünüyorsanız panelden hemen yenileyin.