Webhook entegrasyonunun başarılı olması ham JSON gönderimine değil, payload’un doğru anlaşılmasına bağlıdır. Standart alanları bilmek sürpriz olasılığını azaltır.
Doğru entegrasyon payload’u almak değil payload’u anlamaktır. eventId ve occurredAt — bu iki alan, idempotent bir mimarinin omurgasıdır.
Standart alanlar
- eventId: idempotency için benzersiz id.
- eventType: feedback.created, feedback.lowRating gibi.
- occurredAt: ISO 8601 UTC zaman damgası.
- restaurantId: olayın ait olduğu restoran.
- data: olay özelinde dolan içerik bloğu.
İdempotency uygulaması
Aynı eventId’nin işlemi tekrarlanmamalıdır. Dış sistemde bir tablo veya cache ile son işlenen eventId kümesini tutun. Çok büyük hacimlerde TTL bazlı cache yeterlidir.
Yanıt kuralları
Webhook endpoint’iniz 200 OK ile 5 saniyeden önce yanıt vermelidir. Ağır iş yapıyorsanız önce yanıt verin, ardından arka planda kuyruğa alıp işleyin. Aksi halde sistem retry tetikler ve duplicate işleme riski artar.
Kontrol listesi / Checklist
- eventId tablosu var.
- occurredAt UTC olarak işleniyor.
- Endpoint 5 sn altında 200 OK döner.
- Bilinmeyen eventType graceful handle ediliyor.
- Yanıt kodları izleniyor.
SSS / FAQ
Olmayan bir alanı işlersem hata olur mu?
Yeni alanlar zamanla eklenebilir. Bilinmeyen alanları yok saymak, ileride uyumlu kalmanın en iyi yoludur.
Sıralama garanti mi?
Hayır. Genelde sıralı gelir ama ağ koşulları sıraya etki eder. occurredAt alanına dayanarak işleme tarihini tutun.