Integrasi webhook asinkron pada sistem terdistribusi tidak menjamin urutan pengiriman yang deterministik. Network jitter, kegagalan sementara jaringan, dan kebijakan exponential backoff retry dari webhook provider sering kali menyebabkan mutasi data yang lebih baru tiba lebih awal dibanding mutasi lama. Tanpa penanganan khusus, kondisi out-of-order webhook ini memicu state regression fatal, misalnya pesanan kembali menjadi PENDING setelah sempat berstatus PAID.
Akar Masalah: Network Jitter dan Retry Policy
Penyedia webhook umumnya menggunakan model at-least-once delivery. Dua skenario umum kegagalan urutan:
- Network Jitter: Event V1 dan V2 dikirim hampir bersamaan. Paket V1 terhambat di rute jaringan, sedangkan paket V2 tiba dan diproses lebih dulu oleh server penerima.
- Retry Asymmetric Latency: Pengiriman V1 mengalami timeout di sisi gateway pengirim sehingga dijadwalkan ulang 5 menit kemudian. Sementara itu, event V2 sukses terkirim dan selesai dieksekusi dalam beberapa detik. Ketika retry V1 akhirnya tiba, payload tersebut membawa data usang (stale payload).
Mengandalkan timestamp payload rentan terhadap clock skew antar server. Solusi yang deterministik membutuhkan kombinasi validasi integritas payload, deduplikasi pesan melalui idempotency key, serta kontrol urutan menggunakan monotonic state versioning.
Arsitektur Penanganan: Dua Layer Pertahanan
Pemisahan tanggung jawab dilakukan menjadi dua tahap: deduplikasi di transport/application layer menggunakan Redis, diikuti validasi status stateful di storage layer menggunakan optimistic locking berbasis versi monontonik.
- HMAC Signature Verification: Memastikan payload asli dan belum dimanipulasi pihak ketiga.
- Transport Deduplication (Redis SETNX): Mengabaikan pengiriman ulang instan dari event ID yang identik.
- State Versioning (Monotonic Counter / State Machine Guard): Memastikan pembaruan database hanya terjadi jika versi payload masuk lebih tinggi daripada versi record di database.
Implementasi Validasi Signature dan Redis Idempotency
Endpoint HTTP harus mengembalikan respon 200 OK sesegera mungkin guna mencegah retry berulang dari pengirim. Contoh implementasi backend menggunakan Node.js:
import crypto from 'node:crypto';
import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
export function verifyHmacSignature(rawBody, signatureHeader) {
const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
const digest = 'sha256=' + hmac.update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signatureHeader));
}
export async function acquireIdempotencyLock(eventId, ttlSeconds = 86400) {
// SET with NX ensures atomic lock acquisition only if key does not exist
const result = await redis.set(`webhook:idempotency:${eventId}`, 'PROCESSED', 'EX', ttlSeconds, 'NX');
return result === 'OK';
}
Pola State Versioning dan Atomic Guard pada Database
Untuk menangkal payload usang akibat out-of-order, entitas data wajib memiliki kolom version bernilai integer yang naik secara monotonik (atau sequence state yang terikat). Jangan mengeksekusi operasi UPDATE buta.
Skema tabel relasional pendukung:
CREATE TABLE orders (
id VARCHAR(64) PRIMARY KEY,
status VARCHAR(32) NOT NULL,
version BIGINT NOT NULL DEFAULT 1,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
Ketika webhook tiba membawa payload berisi { "id": "ord_123", "status": "PAID", "version": 2 }, pembaruan data wajib menggunakan conditional update:
UPDATE orders
SET
status = $1,
version = $2,
updated_at = NOW()
WHERE
id = $3
AND version < $2;
Menangani Payload Usang Tanpa Memblokir Throughput
Jika query di atas mengembalikan rows affected = 0 pada data yang terdaftar, dua kemungkinan terjadi: ID tidak ditemukan, atau versi payload yang masuk lebih kecil/sama dengan data saat ini (stale retry). Logika penanganan aplikasi:
async function handleOrderWebhook(orderId, nextStatus, nextVersion) {
const result = await db.query(
'UPDATE orders SET status = $1, version = $2, updated_at = NOW() WHERE id = $3 AND version < $2',
[nextStatus, nextVersion, orderId]
);
if (result.rowCount === 0) {
const existing = await db.query('SELECT version FROM orders WHERE id = $1', [orderId]);
if (existing.rows.length > 0 && existing.rows[0].version >= nextVersion) {
// Stale payload terdeteksi: abaikan mutasi namun balas ACK 200 ke provider
return { status: 'IGNORED_STALE' };
}
throw new Error('Order not found or concurrency conflict');
}
return { status: 'APPLIED' };
}
Penting: Jangan mengembalikan HTTP status 4xx atau 5xx untuk payload yang ditolak akibat versi usang. Mengembalikan error hanya akan memicu pengirim melakukan retry kembali, menciptakan infinite retry loop yang membebani gateway sistem.
Trade-off dan Limitasi
- Gap Versioning: Jika versi bertambah secara berurutan (+1) dan event V2 datang sebelum V1, penolakan langsung atas V1 bisa menghilangkan riwayat intermediet jika V1 membawa metadata non-status. Solusinya: masukkan event ke dalam holding queue terisolasi (misal: Redis ZSET) berjangka waktu pendek jika strict audit trail dibutuhkan.
- Storage Overhead: Idempotency key di Redis membutuhkan alokasi TTL yang tepat. TTL terlalu singkat berisiko meloloskan retry yang tertunda lama; TTL terlalu panjang meningkatkan biaya memori. TTL antara 24 hingga 72 jam umumnya ideal untuk sebagian besar webhook provider komersial.
Komentar
0 komentar
Masuk ke akun kamu untuk ikut berkomentar.
Belum ada komentar
Jadilah yang pertama ikut berdiskusi!