hikiehikieDeveloper Documentation
Entegrasyon

Tekrarları yönetmek

Aynı webhook iki kez gelirse ne olur, nasıl korunursunuz, sıralama neden garanti değil.

Neden aynı webhook iki kez gelir

hikie kendi tarafında çifte tetiklemeyi filtreler — aynı sipariş iki farklı yoldan bildirildiğinde size tek istek gider. Ama şu senaryo filtrelenemez:

sequenceDiagram
participant H as hikie
participant S as Sunucunuz

H->>S: POST (deneme 1)
S->>S: işi yapar (6 sn sürer)
Note over H: 5 sn doldu — zaman aşımı
H--xS: bağlantı kesildi
S->>S: iş tamamlandı ama<br/>yanıt gitmedi
Note over H: 1 dk sonra
H->>S: POST (deneme 2)<br/>AYNI Hikie-Webhook-Id
S->>S: iş İKİNCİ KEZ yapılır ❌

hikie yanıtı alamadığı için teslimatı başarısız sayar ve yeniden dener. Sizin tarafınızda iş tamamlanmıştır. Korunmazsanız müşteriye ürünü iki kez teslim edersiniz.

Bu, "en az bir kez teslimat" (at-least-once) modelinin kaçınılmaz sonucudur. Tekrar koruması alıcının sorumluluğundadır — her ciddi webhook entegrasyonunda olması gerekir.

Anahtar: Hikie-Webhook-Id

Bu başlık teslimatı benzersiz olarak tanımlar ve tüm yeniden denemelerde aynı kalır.

Hikie-Webhook-Id: wh_1f0c8ab29e7d453b6c1a0e94f27d3b85
Ne değişirNe değişmez
Hikie-TimestampHikie-Webhook-Id
Hikie-SignatureGövde (bayt bayt aynı)
Hikie-Delivery-AttemptGövdedeki id alanı

Gövdedeki id alanı da aynı değeri taşır; başlığa erişemiyorsanız oradan okuyabilirsiniz.

Doğru desen: atomik "gördüm mü" kontrolü

Kontrol ve işaretleme tek atomik adımda olmalı. Ayrı GET + SET kullanmak, aynı webhook paralel iki worker'a düşerse ikisinin de "yeni" görmesine yol açar.

const TTL_SECONDS = 7 * 24 * 60 * 60; // 7 gün

async function claimWebhook(webhookId) {
  // SET NX EX: yoksa yaz ve 'OK' dön, varsa null dön.
  const written = await redis.set(`hikie:wh:${webhookId}`, '1', {
    NX: true,
    EX: TTL_SECONDS,
  });

  return written !== null; // true = ilk kez görüyoruz
}

Kullanımı:

if (!(await claimWebhook(webhookId, eventType))) {
  return res.sendStatus(200); // zaten işlendi
}

await enqueue({ eventType, webhookId, payload });
res.sendStatus(200);

Kaydı ne kadar saklamalı: retry penceresi 72 saat, yani teknik olarak 4 gün yeterli. 7 gün rahat bir tampon bırakır ve pratikte maliyeti yok denecek kadar azdır.

İşin kendisini de idempotent yapın

Tekrar kaydı ilk savunma hattıdır, ama tek başına yeterli değildir: kaydı yazdıktan sonra ve işi bitirmeden önce süreciniz çökebilir. Mümkün olan yerde işin kendisi de tekrara dayanıklı olsun.

YerineBunu yapın
bakiye = bakiye + 250INSERT ... ON CONFLICT DO NOTHING ile işlem kaydı, bakiyeyi ondan türet
üyelik_bitis += 30 günüyelik_bitis = MAX(mevcut, hesaplanan_yeni_tarih)
Her çağrıda e-posta gönderGönderim kaydını webhookId ile tekil tut

Örnek — abonelik uzatma:

// ❌ Tekrarda üyeliği iki kat uzatır
await db.query('UPDATE members SET expires_at = expires_at + interval \'30 days\' WHERE id = $1', [id]);

// ✅ Kaç kez çalışırsa çalışsın aynı sonucu verir
await db.query(
  'UPDATE members SET expires_at = GREATEST(expires_at, $2) WHERE id = $1',
  [id, payload.dateCurrentPeriodEnd],
);

Payload'daki endDate, cycle, paidAt gibi alanlar tam bu yüzden var: mutlak değerler gönderiyoruz ki siz artırma yerine atama yapabilesiniz.

Sıralama garanti değil

Eventler üretildikleri sırayla gönderilmeye çalışılır ama sıra garanti edilmez. Bir teslimat yeniden denemeye düşerse ondan sonra üretilen bir olay ona yetişebilir.

Gerçekçi bir senaryo:

sequenceDiagram
participant H as hikie
participant S as Sunucunuz

Note over H: 10:00 order.shipmentUpdated (Fulfilled) üretildi
H->>S: POST Fulfilled
S--xH: timeout
Note over H: 10:05 order.shipmentUpdated (CargoDelivered) üretildi
H->>S: POST CargoDelivered ✅
Note over H: 10:01 → Fulfilled yeniden denenir
H->>S: POST Fulfilled ✅ (SIRA BOZULDU)

Korunma yolu: her kaydın son bilinen durumunu Hikie-Occurred-At başlığındaki damgayla birlikte tutun ve daha eskisini yok sayın.

const incoming = new Date(req.get('Hikie-Occurred-At'));

const current = await db.getOrder(payload.orderId);
if (current && new Date(current.lastEventAt) >= incoming) {
  return; // daha eski ya da eşit bir olay — atla
}

await db.updateOrder(payload.orderId, {
  ...payload,
  lastEventAt: incoming,
});

Hikie-Occurred-At, işin gerçekten olduğu andır — isteğin size ulaştığı an değil. Karşılaştırmayı kendi saatinizle değil, kaydettiğiniz önceki damgayla yapın.

Özet kontrol listesi

Bu sayfada