Webhook delivery neden güvenilir financial integration için yeterli değildir?

Delivery acknowledgement tek boundary'dir

HTTP 2xx receiving service'in request'i accepted, queued veya fully processed ettiği anlamına gelebilir. Bunlar farklı guarantee'lerdir. Financial workflow event'in hangi noktada durable olduğunu ve transport acknowledgement sonrası processing fail olursa ne olacağını açıkça tanımlamalıdır.

Consumer idempotent event handling yapmalı

Webhook provider acknowledgement fail olursa delivery'yi retry edebilir. Receiving system duplicate delivery mümkünmüş gibi davranmalı ve stable event identity veya business key ile idempotent processing yapmalıdır. Deduplication process restart sonrası da yaşamalıdır; in-memory set yeterli değildir.

Ordering varsayılmamalı, modellenmeli

Distributed event geç veya out-of-order gelebilir. Network order business order kabul edilmemelidir. Resource version, event timestamp, state transition veya reconciliation read event'in hâlâ applicable olup olmadığını belirlemelidir.

Recovery için başka source of truth gerekir

Event kalıcı olarak kaybolursa veya consumer misconfigured ise state rebuild yolu gerekir. Periodic reconciliation, provider fetch API, replayable event store veya backfill endpoint bu recovery path'i sağlar. Aksi halde webhook reliability tek mesajın gelmesine bağlı kalır.

Delivery, acceptance ve processing'i farklı event olarak tanımlayın

Provider'ın webhook göndermesi, edge'in alması, application'ın kabul etmesi ve domain transaction'ın başarılı commit edilmesi farklı event'lerdir. System 2xx'in hangi boundary'yi acknowledge ettiğini bilmelidir. Endpoint durable persistence öncesi success dönerse crash event'i kaybettirebilir ve provider retry'ı durmuş olur. Uzun downstream workflow'u beklerse provider retry unnecessary duplicate yaratabilir.

Yaygın pattern event'i authenticate ve validate etmek, durable biçimde persist veya enqueue etmek, hızlı acknowledge etmek ve domain processing'i bu durable record'dan yürütmektir. Implementation değişebilir; ancak boundary intentional ve observable olmalıdır.

Delivery'yi brittle yapmadan event authenticate edin

Webhook security çoğunlukla provider signature veya secret verification, timestamp validation ve transport security içerir. Provider raw payload veya prescribed canonical form istiyorsa verification bunu kullanmalıdır; JSON'u parse edip yeniden serialize etmek signature'ı bozabilir. Key rotation ve clock skew da operational handling gerektirir.

Security failure application failure'dan ayrı metric olmalıdır. Signature failure'da ani artış misconfiguration, rotation problemi veya malicious traffic gösterebilir; generic 4xx olarak görmek cause'u saklar.

Idempotency'yi domain boundary'de tasarlayın

Provider event ID ile deduplication aynı event'in tekrar delivery'sinin side effect'i yinelemesini engeller; ancak farklı transport identity taşıyan semantically duplicate event'leri engellemeyebilir. Business action önemliyse—invoice'ı paid işaretlemek veya refund record yaratmak gibi—domain constraint ve state transition ikinci safety layer olmalıdır.

Idempotent processing email, ledger entry, inventory change ve downstream message gibi side effect'leri de kapsamalıdır. Database'i idempotent update edip customer'a iki notification gönderen handler operational olarak idempotent değildir.

Ordering'i state-machine problemi olarak ele alın

Network related event'lerin business'ın beklediği sırada geleceğini garanti etmez. Later state önce gelebilir veya older event newer event işlendikten sonra retry edilebilir. Consumer resource version, timestamp, sequence data veya gerektiğinde fresh provider read kullanarak transition'ın hâlâ legal olup olmadığını doğrulamalıdır.

Amaç her event'i global olarak sort etmek değildir. Amaç domain'in impossible state'e regress etmesini engellemektir. Payment state machine repeated ve delayed evidence'ı final result'ı bozmadan tolere etmelidir.

Replay ve reconciliation'ı ilk günden kurun

Deployment error, expired credential, configuration mistake veya provider incident nedeniyle bazı live event'lerin kaçacağını varsayın. Safe replay için yeterli event history veya provider reference tutun. Silent gap, delivery anında alert oluşmasa bile bulunabilsin diye important resource'ları periyodik olarak provider ile reconcile edin.

Bu recovery design incident response'u değiştirir. Operator 'her webhook geldi mi?' diye sormak yerine 'local financial state'in doğru olduğu kanıtlanabiliyor mu; değilse hangi cohort replay veya reconciliation gerektiriyor?' diye sorar. Bu daha güçlü reliability objective'tir.