Webhook vs Polling Reconciliation

Webhook ve polling birbirinin alternatifi değildir. Production travel sisteminde webhook hızlı evidence, polling/reconciliation ise tamlık ve recovery mekanizmasıdır.

Reference flow

Webhook and reconciliation architecture

Mermaid source (.mmd)

Webhook neden tek başına yetmez?

Webhook:

• kaybolabilir,
• duplicate gelebilir,
• out-of-order gelebilir,
• provider retry edebilir,
• imza doğrulaması başarısız olabilir,
• endpoint kısa süre unavailable olabilir.

Bu yüzden "webhook gelmedi = event olmadı" kabulü güvenli değildir.

Polling neden tek başına yetmez?

Sürekli polling:

• rate limit tüketir,
• gereksiz trafik üretir,
• state propagation'ı geciktirir,
• provider maliyetini artırabilir.

Polling hedefli ve state-aware olmalıdır.

Reconciliation scheduling

Aday kayıtlar:

• uzun süredir UNKNOWN/PENDING,
• webhook beklenen ama gelmeyen booking,
• payment ve booking state'i ayrışan kayıt,
• cancellation/refund incomplete,
• provider reference var ama local terminal state yok.

Backoff kullanın:

1 min -> 5 min -> 15 min -> 1 h -> manual threshold

Dedup ve ordering

Webhook ingress event'i doğrudan state update etmemeli. Önce:

1. signature/auth verify,
2. provider event identity çıkar,
3. dedup,
4. occurredAt / sequence kaydet,
5. transition rules çalıştır.

Out-of-order event daha yeni state'i geri almamalıdır.

Source precedence

Çelişen evidence için precedence tanımlayın. Örnek:

authoritative status lookup
> signed provider webhook
> synchronous API response
> local inferred timeout state

Bu sıra provider'a göre değişebilir ama explicit olmalıdır.

Failure modes

• duplicate webhook,
• webhook replay attack,
• stale event'in state'i geri alması,
• polling storm,
• reconciliation'ın aynı booking'i paralel işlemesi,
• provider lookup eventual consistency nedeniyle geçici yanlış sonuç.

Observability

• webhook receive rate,
• signature failure,
• duplicate ratio,
• out-of-order ratio,
• webhook-to-state latency,
• reconciliation queue depth,
• reconciliation resolution rate,
• pending/unknown age buckets.

Production checklist

• signature/auth verification,
• idempotent event apply,
• event store,
• ordering/version strategy,
• state-aware polling,
• exponential backoff,
• reconciliation ownership lock,
• manual escalation threshold.