Temel Kavramlar

Bu Kavramlar Neden Önemli

Webhook sistemleri yüzeyde basit görünür — sadece bir HTTP POST gönderin. Ancak üretimde hızla sorunlarla karşılaşırsınız:

• Alıcının sunucusu çöktüğünde ne olur?
• Webhook'un gerçekten sizden geldiğini nasıl kanıtlarsınız?
• Alıcıyı bunaltmadan binlerce webhook'u nasıl yönetirsiniz?
• Bir şey yanlış gittiğinde nasıl debug edersiniz?

HookSniff'in temel kavramları bu sorunların her birini çözer. İşte nasıl bir araya geldikleri.

Endpoint'ler

Bir uç nokta, HookSniff'in webhook'ları teslim ettiği bir URL'dir. Bunu webhook'larınız için bir 'posta adresi' gibi düşünün.

Uç noktaların önemi: Uygulamanızda URL'leri kodlamak yerine, uç noktaları HookSniff'e kaydedersiniz. Bu, hedefi kod değişikliği olmadan değiştirmenizi, olay filtreleri eklemeniz ve hedef başına teslimat sağlığını takip etmenizi sağlar.

Her uç noktanın şunları vardır:

• URL — Webhook POST isteklerini alan hedef
• İmza gizli anahtarı — Payload doğrulama için HMAC-SHA256 gizli anahtarı (whsec_ öneki)
• Olay filtresi — İsteğe bağlı: yalnızca belirli olay türlerini teslim edin (ör. order.*)
• Durum — Aktif veya pasif; pasif uç noktalar teslimatı atlar
• Tekrar politikası — Uç nokta başına özel tekrar davranışı

{
  "id": "ep_abc123",
  "url": "https://myapp.com/webhook",
  "description": "Order notifications",
  "signing_secret": "whsec_abc123xyz789...",
  "is_active": true,
  "event_filter": "order.*",
  "created_at": "2026-01-15T10:30:00Z"
}

Webhook'lar ve Teslimatlar

Bir webhook, API üzerinden gönderdiğiniz bir olaydır. Bir teslimat, HookSniff'in bu webhook'u bir uç noktaya teslim etme denemesidir.

Ayrım önemlidir: Bir webhook birden fazla teslimata sahip olabilir (tekrar denemeler, birden fazla uç nokta). Her teslimat kendi durumu, denemeleri ve zamanlamasıyla bağımsız olarak takip edilir.

• Olay türleri — order.created, user.updated gibi dizi tanımlayıcıları
• Payload'lar — İstek gövdesi olarak gönderilen JSON verisi
• Teslimat durumu — pending, delivered veya failed
• Deneme takibi — Her teslimat denemesi durum kodu, yanıt gövdesi ve süre ile kaydedilir
• İdempotans — Tekrarlanan teslimatları önlemek için Idempotency-Key başlığını kullanın

curl -X POST https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks \
  -H "Authorization: Bearer hr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ep_abc123",
    "event": "order.created",
    "data": { "order_id": "12345", "total": 99.99 }
  }'

Yeniden Denemeler

Sorun: Sunucular çöker, ağlar aksar, dağıtımlar olur. Bir webhook teslimatı başarısız olursa, olayı kaybetmek istemezsiniz.

Çözüm: HookSniff, başarısız teslimatları jitter ile üstel geri çekilme kullanarak otomatik olarak tekrar dener. Her tekrar bir öncekinden daha uzun bekler, bu da çılgın kalabalık sorununu önler.

Varsayılan program (5 deneme, endpoint başına yapılandırılabilir):

Tüm 5 yeniden deneme tükendikten sonra, teslimat Dead Letter Queue ya taşınır. Retries & DLQ

Dead Letter Queue (DLQ)

Sorun: Tüm tekrarlar başarısız olduktan sonra, olaya ne olur? DLQ olmadan, sessizce kaybolur.

Çözüm: Başarısız teslimatlar, orijinal payload, her denemenin durum kodu, yanıt gövdesi ve zamanlama dahil tam bağlamla DLQ'da korunur. İnceleyebilir, neyin yanlış gittiğini anlayabilir ve tek tıklamayla tekrar oynatabilirsiniz.

• Orijinal payload korunur
• Tüm deneme detayları (durum kodları, hatalar, zaman damgaları)
• Tekrar oynatma yeteneği — teslimatı başka bir deneme için tekrar kuyruğa alın
• Plana göre saklama (Developer: 7 gün, Startup: 14 gün, Pro: 180 gün, Enterprise: 365 gün)

API Anahtarları

Sorun: Şifrenizi paylaşmadan API isteklerini nasıl doğrularsınız?

Çözüm: API anahtarları hr_live_ önekli uzun ömürlü token'lardır. Birden fazla anahtar oluşturabilir (servis veya ekip üyesi başına bir tane) ve kesinti olmadan döndürebilirsiniz.

Authorization: Bearer hr_live_abc123xyz789

• Anahtarlar veritabanında Argon2 ile hashlenir — düz metin asla saklanmaz
• Hesap başına birden fazla anahtar — kesinti olmadan döndürme
• Planınızın hız limitlerine tabi
• Her anahtar dashboard'da yalnızca önekini gösterir — tam anahtar oluşturulurken bir kez gösterilir

FIFO Teslimat

Sorun: order.created ve order.updated webhook'larını art arda gönderirseniz, güncelleme olayı oluşturma olayından önce gelebilir. Tüketiciniz bunları sırasız işler.

Çözüm: HookSniff, uç nokta başına FIFO (ilk giren ilk çıkar) sırasıyla webhook teslim eder. Her teslimat, tüketicilerin boşlukları algılaması veya olayları yeniden sıralaması için bir sıra numarası içerir.

{
  "delivery_id": "wh_xyz789",
  "sequence_number": 42,
  "event": "order.created",
  "data": { "order_id": "12345" },
  "timestamp": "2026-01-15T10:30:00Z"
}