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şir | Ne değişmez |
|---|---|
Hikie-Timestamp | Hikie-Webhook-Id |
Hikie-Signature | Gövde (bayt bayt aynı) |
Hikie-Delivery-Attempt | Gö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.
| Yerine | Bunu yapın |
|---|---|
bakiye = bakiye + 250 | INSERT ... 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önder | Gö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.