Webhook Replay ve Idempotency Troubleshooting

Webhook sistemlerinde duplicate delivery normal kabul edilmelidir. Problem duplicate'in gelmesi değil, aynı business event'in birden fazla kez uygulanmasıdır.

Symptom

Aynı booking iki kez update olur, refund iki kez işlenir, event sırası bozulur veya replay sonrası eski state geri gelir.

Diagnosis

1. Provider event ID stable mı?
2. Aynı payload kaç kez geldi?
3. occurredAt ve receivedAt farkı ne?
4. Event önce uygulanmış mı?
5. State transition replay-safe mi?
6. Eski event yeni state'i overwrite ediyor mu?

Idempotency

Provider event ID varsa dedup key olarak kullanın. Yoksa provider + entity + event type + source timestamp/payload hash kombinasyonu kullanılabilir.

Replay

Replay endpoint/job aynı event set'ini tekrar işlediğinde state değişmemelidir. Side-effect'ler idempotent veya transactional guard ile korunmalıdır.

Possible causes

Duplicate event, out-of-order event, partial transaction, dedup store expiry, provider'ın event ID reuse etmesi ve poison event.

Recovery

Aynı event'i kontrollü biçimde iki kez gönderin; business state ve side-effect yalnız bir kez değişmeli.

Observability

Duplicate delivery rate, dedup hit, out-of-order rate, replay failure, poison-event count ve event processing lag.

Prevention

Dedup retention süresini provider replay window'dan kısa tutmayın; state transition'ları explicit version/sequence ile koruyun.

Out-of-order event recovery

Yeni state'i eski event ile geri almayın. Event sequence varsa monotonik kontrol kullanın; yoksa provider event timestamp, local version ve allowed-transition kuralları birlikte değerlendirilmelidir.

Örnek: CANCELLED state'e ulaşmış booking'e daha sonra gelen eski CONFIRMED event'i uygulanmamalıdır. Event audit trail'de kalır ancak materialized state'i değiştirmez.

Validation

Aynı booking için CONFIRMED → CANCELLED → gecikmiş CONFIRMED sırasını kontrollü test edin. Son state CANCELLED kalmalı ve stale event observability'de görünmelidir.