Merancang Webhook yang Andal: Retry, Signing, dan Replay

Webhook terlihat sederhana dari luar: sistem Anda mendeteksi sebuah event, mengirim HTTP POST ke URL yang didaftarkan konsumen, lalu selesai. Pada praktiknya, satu kalimat itu menyembunyikan masalah sistem terdistribusi yang nyata. Server konsumen bisa saja sedang down untuk maintenance. Jaringan bisa saja kehilangan respons setelah konsumen sebenarnya sudah memproses event tersebut. Proses deploy bisa saja me-restart worker pengiriman Anda di tengah request. Semua kegagalan ini adalah hal rutin, bukan pengecualian, dan sistem webhook yang mengabaikannya cepat atau lambat akan mengirim event dua kali, kehilangan event selamanya, atau membiarkan penyerang memalsukan payload yang terlihat sah.

Tulisan ini membahas empat pilar sistem webhook yang bisa dijadikan fondasi integrasi produksi oleh konsumen: menandatangani setiap payload agar konsumen bisa memverifikasi keasliannya, mengulang pengiriman yang gagal dengan backoff alih-alih membombardir endpoint yang sedang bermasalah, memberi konsumen cara aman menangani pengiriman duplikat, serta menjaga log event yang persisten agar kedua pihak bisa memutar ulang riwayat saat ada yang salah. Semua ini bukan hal eksotis. Ini adalah pola-pola yang sama yang secara independen dipakai oleh penyedia payment gateway dan platform API besar.

Mengapa pengiriman at-least-once adalah jaminan paling jujur

Ada tiga jaminan pengiriman yang secara teori bisa ditawarkan: at-most-once, exactly-once, dan at-least-once. At-most-once berarti event bisa saja hilang tanpa jejak, yang tidak bisa diterima untuk apa pun yang diandalkan konsumen untuk penagihan, inventaris, atau sinkronisasi state. Exactly-once terdengar ideal tetapi tidak bisa dicapai melalui batas jaringan yang tidak dapat diandalkan tanpa kerja sama konsumen, karena Anda tidak bisa tahu apakah request Anda berhasil jika acknowledgment hilang di tengah jalan. Karena itu at-least-once adalah satu-satunya jaminan yang jujur bisa Anda berikan: setiap event dikirim satu kali atau lebih, dan tugas konsumenlah memperlakukan pengiriman duplikat sebagai hal wajar, bukan bug.

• Rancang pengirim dengan asumsi setiap upaya pengiriman bisa saja diulang, bukan dengan asumsi hanya dikirim tepat sekali.
• Dokumentasikan jaminan ini secara eksplisit di dokumentasi webhook Anda agar konsumen membangun deduplikasi sejak awal, bukan menemukannya setelah masuk produksi.
• Beri setiap event pengenal unik yang stabil dan tetap sama di setiap retry, sehingga konsumen punya sesuatu yang konkret untuk dijadikan acuan deduplikasi.

Menandatangani payload agar konsumen bisa mempercayai pengirim

Siapa pun bisa mengirim HTTP POST ke URL publik, sehingga endpoint konsumen butuh cara untuk memastikan request benar-benar berasal dari Anda dan bukan hasil pemalsuan atau replay oleh penyerang yang mencegat pengiriman lama. Pendekatan standarnya adalah HMAC: Anda dan konsumen berbagi secret, dan setiap request keluar menyertakan signature yang dihitung dari hash badan request digabung dengan secret dan timestamp tersebut. Konsumen menghitung ulang hash yang sama di sisi mereka dan membandingkannya dengan signature yang Anda kirim. Jika cocok, payload dianggap asli dan tidak diubah; jika tidak, konsumen menolak request tersebut sepenuhnya.

// Signing an outgoing webhook payload — Node.js
import crypto from "node:crypto"

function signPayload(rawBody: string, secret: string, timestamp: number) {
  const signedPayload = `${timestamp}.${rawBody}`
  const signature = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex")
  return `t=${timestamp},v1=${signature}`
}

// Consumer-side verification (constant-time compare)
function verifySignature(rawBody: string, header: string, secret: string, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=") as [string, string])
  )
  const timestamp = Number(parts.t)
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) {
    throw new Error("Timestamp outside tolerance window")
  }
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(parts.v1)
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    throw new Error("Invalid signature")
  }
}

Dua detail membedakan implementasi yang benar dari yang keliru. Pertama, timestamp harus menjadi bagian dari konten yang ditandatangani dan konsumen harus menolak signature di luar jendela toleransi, biasanya sekitar lima menit, karena kalau tidak, penyerang yang menangkap satu request valid bisa memutarnya ulang tanpa batas. Kedua, perbandingan antara signature hasil hitungan dan signature yang diterima harus berjalan dalam waktu konstan. Perbandingan string naif yang langsung berhenti begitu menemukan karakter yang tidak cocok membocorkan informasi waktu yang bisa dimanfaatkan penyerang untuk menebak signature yang benar satu byte demi satu byte.

Retry dengan exponential backoff, bukan jadwal tetap

Ketika sebuah upaya pengiriman gagal, entah karena timeout, respons lima ratus, atau koneksi yang terputus, perbaikan naif adalah langsung mengulang beberapa kali dengan jadwal tetap. Pendekatan itu justru memperburuk keadaan: jika endpoint konsumen down karena kelebihan beban, badai retry langsung dari setiap event yang Anda coba kirim hanya memperdalam gangguan itu. Solusinya adalah exponential backoff, di mana setiap retry menunggu lebih lama dari sebelumnya, dipadukan dengan sedikit jitter acak agar banyak pengiriman yang antre tidak sekaligus bangun dan retry pada saat yang persis sama.

Baris terakhir itu sama pentingnya dengan baris-baris awal. Retry tanpa henti membuang sumber daya pada endpoint yang sudah benar-benar hilang, misalnya konsumen yang menghapus integrasinya berbulan-bulan lalu. Setelah anggaran retry habis, pindahkan pengiriman itu ke status dead letter, beri tahu konsumen lewat dashboard atau ringkasan email, dan biarkan mereka memicu replay manual setelah memperbaiki apa pun yang rusak di sisi mereka.

Idempotency: membuat duplikat tidak berbahaya

Karena jaminan pengiriman at-least-once memastikan duplikat akan terjadi, handler di sisi konsumen perlu bersifat idempotent, artinya memproses event yang sama dua kali menghasilkan state akhir yang sama seperti memprosesnya sekali. Ini adalah tugas kedua belah pihak: Anda menyediakan pengenal event yang stabil, dan konsumen menyimpan pengenal mana saja yang sudah mereka proses. Polanya cukup sederhana untuk diimplementasikan dengan benar.

1. Buat pengenal unik dan stabil untuk setiap event sejak saat pembuatannya, sebelum upaya pengiriman apa pun, dan jangan pernah mengubahnya di setiap retry.
2. Minta konsumen memeriksa pengenal itu terhadap tabel kecil berisi event yang sudah diproses sebelum melakukan pekerjaan yang berefek samping, seperti menagih kartu atau memperbarui inventaris.
3. Minta konsumen mencatat pengenal sebagai sudah diproses dalam transaksi database yang sama dengan efek sampingnya sendiri, sehingga crash di antara dua langkah itu tidak membuat duplikat lolos.
4. Kembalikan respons sukses untuk pengenal yang sudah diproses sebelumnya, bukan error, karena dari sudut pandang pengirim, event tersebut memang sudah ditangani.

Log event: sumber kebenaran untuk replay

Setiap event yang akan Anda kirim seharusnya lebih dulu ditulis ke log event yang persisten, terpisah dari upaya pengiriman itu sendiri. Pemisahan ini penting karena memisahkan pertanyaan apa yang terjadi di sistem Anda dari pertanyaan apakah endpoint konsumen tertentu berhasil menerimanya. Dengan pemisahan itu, replay menjadi operasi sederhana: masukkan baris pengiriman baru yang menunjuk ke event yang sudah ada dan biarkan worker pengiriman Anda mengambilnya sesuai jadwal normalnya.

-- Event log table for replay support
CREATE TABLE webhook_events (
  id UUID PRIMARY KEY,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE webhook_deliveries (
  id UUID PRIMARY KEY,
  event_id UUID NOT NULL REFERENCES webhook_events(id),
  endpoint_id UUID NOT NULL,
  status TEXT NOT NULL, -- pending | delivered | failed | dead_letter
  attempt_count INT NOT NULL DEFAULT 0,
  next_attempt_at TIMESTAMPTZ,
  last_response_code INT,
  UNIQUE (event_id, endpoint_id)
);

-- Replaying a single event to a single endpoint on demand
INSERT INTO webhook_deliveries (id, event_id, endpoint_id, status, next_attempt_at)
VALUES (gen_random_uuid(), $1, $2, 'pending', now())
ON CONFLICT (event_id, endpoint_id) DO UPDATE
  SET status = 'pending', next_attempt_at = now();

Log event juga bermanfaat jauh melampaui pemulihan error. Konsumen dengan bug di versi handler yang lebih lama bisa meminta replay event seminggu terakhir setelah merilis perbaikan. Integrasi baru yang baru saja dikonfigurasi bisa mengisi state awalnya dari event historis alih-alih menunggu kemunculan berikutnya dari tiap jenis event. Jaga agar log tetap immutable, simpan event untuk jendela waktu terbatas yang sesuai kebutuhan kepatuhan dan penyimpanan Anda, dan indeks berdasarkan jenis event serta waktu pembuatan agar replay per kategori tetap murah.

Pengaman operasional yang layak dibangun sejak awal

Beberapa keputusan kecil menentukan apakah sistem webhook tetap sehat saat berkembang dari segelintir konsumen menjadi ratusan atau ribuan endpoint terdaftar.

• Terapkan timeout request yang ketat, biasanya beberapa detik, agar satu konsumen yang lambat tidak menahan worker pengiriman yang dibutuhkan konsumen lain.
• Lacak tingkat kegagalan per endpoint dan secara otomatis jeda atau tandai endpoint yang gagal hampir di setiap pengiriman, alih-alih terus mengulang integrasi yang sudah mati selamanya.
• Beri versi eksplisit pada skema payload Anda dan jangan pernah menghapus field yang mungkin sudah diandalkan konsumen; tambahkan field baru saja, dan hanya perkenalkan perubahan yang tidak kompatibel lewat versi payload baru yang dipilih sendiri oleh konsumen.

Keempat pilar ini, signing, backoff, idempotency, dan log yang bisa diputar ulang, tidak sulit satu per satu. Kesulitannya ada pada memperlakukannya sebagai satu sistem yang utuh sejak awal, bukan menambalnya setelah insiden produksi pertama. Konsumen menilai API webhook dari perilakunya di hari terburuk mereka, bukan hari terbaiknya, dan rancangan yang dibangun di atas pengiriman at-least-once dengan perkakas yang membuat duplikat dan gangguan bukan lagi masalah besar adalah yang benar-benar mendapatkan kepercayaan mereka.