hikiehikieDeveloper Documentation
Entegrasyon

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:

FrameworkYöntem
Expressexpress.raw({ type: 'application/json' })
FastifyaddContentTypeParser ile buffer saklamak
NestJSNestFactory.create(AppModule, { rawBody: true })
Next.jsawait 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  # macOS

System 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ıyorsunuzDoğ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

KodMuhtemel sebep
400İmza doğrulamanız reddediyor, ya da gövde çözümlemeniz hata veriyor
401 / 403WAF/güvenlik duvarı engelliyor, ya da endpoint'iniz hikie'nin gönderemeyeceği bir kimlik doğrulaması bekliyor
404Abonelikteki yol yanlış, ya da rota tanımlı değil
405Rota POST kabul etmiyor
413Gövde boyutu sınırınız çok düşük — büyük sepetli siparişlerde olur
415application/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_allowedhttps:// değil
blocked_credentials_in_urlURL içinde kullanıcı adı/şifre var
blocked_loopback_addresslocalhost veya 127.x.x.x
blocked_private_addressÖzel ağ adresi, .internal veya .local
blocked_link_local_address169.254.x.x
blocked_reserved_addressAyrılmış IP aralığı
blocked_invalid_urlURL çö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-Id değ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.

Bu sayfada