Webhook İyileştirmeleri Paketi

Webhook altyapısını dört noktada iyileştirdik. Bağlantılarınız dayanıklı, hatalar gözden kaçmıyor, dokümantasyon eksiksiz.

1. Kuruluş Geneli Dispatch (Kritik Düzeltme)

Bir kuruluşa kayıtlı webhook, eskiden sadece webhook’u kuran kişinin event’lerinde tetikleniyordu. Yani kuruluştaki diğer üyelerin oluşturduğu sözleşmeler webhook’a uğramıyordu — sessiz bir veri kaybıydı.

Düzeltildi. Kuruluş webhook’ları artık tüm üyelerin event’lerini yakalar. Kişisel webhook’lar (kişisel çalışma alanından kayıtlı olanlar) eskiden olduğu gibi sadece kayıt sahibinin event’lerine reaksiyon verir.

2. Tekrar Gönderme

Bir webhook teslimatı başarısız oldu mu? Dashboard’da artık iki yeni eylem var:

POST /api/client/webhooks/:id/deliveries/:delivery_id/redeliver

Tek bir teslimatı yeniden tetikler. Yeni bir kayıt oluşturur (orijinali bozmaz), aynı payload, aynı event tipiyle.

POST /api/client/webhooks/:id/redeliver-recent?count=10

Son N teslimatı toplu olarak yeniden tetikler. Webhook adresiniz geçici olarak çöktüyse, ayağa kalktığında bu çağrıyla son 10/50/100 event’i toparlayabilirsiniz.

Her iki endpoint dashboard’da da buton olarak çalışır: webhook detay sayfasındaki teslimat tablosunda her satırın yanında “Tekrar Gönder” butonu, üstte ise “Son 10’u Tekrar Gönder” toplu eylem var.

3. Hata Uyarıları (Otomatik)

Webhook adresiniz 5 ardışık başarısız delivery aldıysa, kuruluşun OWNER ve ADMIN üyelerine tek seferlik sarı uyarı e-postası gönderilir:

⚠️ Webhook’unuz hata alıyor. Adresinizi kontrol edin.

7 gün içinde düzelmezse:

🛑 Webhook’unuz otomatik olarak kapatıldı.

Otomatik kapatma sonrası uyarı tekrar e-posta ile gelir. Düzeltme sonrası dashboard’dan tek tıkla yeniden aktive edebilirsiniz. Bu mekanizma sayesinde “webhook’um neden çalışmıyor?” diyecek kullanıcı kalmaz — proaktif olarak bilgilendirilirsiniz.

4. Tam API Dokümantasyonu Yayınlandı

https://api-docs.imzala.org/#tag/Webhooks adresinde detaylı webhook bölümü canlı:

• 6 olay türü tablosu — demand.created, demand.completed, demand.expired, party.signed, party.viewed, party.rejected
• 5 standart header (X-Imzala-Signature, X-Imzala-Event, X-Imzala-Delivery, vb.)
• Payload zarf yapısı ve gerçek örnek JSON
• HMAC-SHA256 imza doğrulama (Express örneği dahil)
• Retry politikası: 6 deneme + üstel geri çekilme (exponential backoff)
• Idempotency: aynı X-Imzala-Delivery ID’si tekrar gelirse atlayın
• Backfill bayrağı: _backfill: true — tarihsel event olduğunu gösterir
• 6 best practice tavsiyesi

OpenAPI 3.1 üst-düzey webhooks: bloğu da ekledik — Postman/Insomnia gibi araçlar webhook tanımlarını otomatik içe aktarabilir.

Yan Bonus: Tablo’da Sözleşme Sütunu

Dashboard’daki teslimat geçmişi tablosuna Sözleşme sütunu eklendi — payload’dan otomatik çıkarılır, tıklanabilir, ilgili sözleşmeye götürür. Hangi event’in hangi sözleşmeye ait olduğunu artık tahmin etmek zorunda kalmazsınız.