Pendahuluan dan Solusi Langsung

Dalam integrasi webhook eksternal, Retry Webhook Idempoten adalah mekanisme utama untuk memastikan event tidak hilang saat jaringan atau sistem penerima gagal sementara. Artikel ini menjelaskan desain kontrak webhook yang menjamin idempoten, mekanisme acknowledgement, rate limit dan backoff, serta logging audit untuk inspeksi dan monitoring delivery.

Anda akan mendapatkan pola payload, header, status response, metode pencatatan audit, dan metrik monitoring termasuk retry count dan dead-letter queue untuk menjaga konsistensi integrasi.

Mendesain Kontrak Webhook Idempoten

Penentuan Idempotent Key

Idempotent key harus unik untuk setiap event logis dan tetap sama saat webhook dikirim ulang. Idealnya terdiri dari kombinasi sumber event dan timestamp atau sequence yang tidak berubah. Contoh:

{
  "X-Idempotency-Key": "order-1234-event-20241014",
  "payload": {...}
}

Penerima menyimpan key ini selama window tertentu (misalnya 1 jam) untuk mendeteksi retry. Jika processing sebelumnya sukses, cukup mengembalikan status 200 tanpa menjalankan ulang bisnis logic.

Mekanisme Acknowledgement dan Status

Gunakan status HTTP konvensional: 200 OK untuk success, 202 Accepted jika proses asinkron dilanjutkan, 429 untuk rate limit, dan 5xx untuk gagal yang butuh retry. Sertakan body minimal yang menjelaskan status:

{
  "status": "ok",
  "message": "event processed",
  "processed_at": "2024-10-14T12:03:22Z"
}

Pada 429 atau 5xx, client webhook harus menganggap ini signal untuk retry dengan backoff. Acknowledgement eksplisit membantu penerima membedakan retry versus duplicate.

Rate Limit, Backoff, dan Retry Strategy

Kontrak harus menyertakan rate limit header dan waktu backoff agar klien tidak membanjiri sistem yang sedang menghadapi beban:

  • X-RateLimit-Limit: maksimum request per detik.
  • X-RateLimit-Remaining: sisa quota.
  • Retry-After: waktu dalam detik sebelum mencoba ulang (valid untuk 429 dan 503).

Di sisi pengirim, terapkan exponentially increasing backoff dengan jitter untuk menghindari efek sinkronisasi saat banyak webhook gagal bersamaan. Batasi total retry (misalnya 5 percobaan) sebelum memindahkan payload ke dead-letter queue (DLQ).

Payload, Header, dan Contoh Retry

Berikut pola payload dan header untuk memudahkan integrasi:

{
  "headers": {
    "Idempotency-Key": "order-1234-event-20241014",
    "X-Webhook-Timestamp": "2024-10-14T12:01:00Z",
    "Content-Type": "application/json"
  },
  "payload": {
    "event": "order.updated",
    "data": {
      "order_id": "1234",
      "status": "shipped"
    }
  }
}

Jika penerima membalas 200, sistem pengirim menandai event selesai. Jika status 5xx, pengirim mencatat retry dan menunggu sesuai backoff sebelum mengirim ulang dengan header yang sama.

Audit dan Logging untuk Inspeksi

Setiap percobaan pengiriman harus dicatat dengan metadata: idempotent key, status response, latency, dan jumlah retry. Gunakan sistem log terstruktur atau tracing agar mudah dicari. Contoh struktur log:

{
  "idempotent_key": "order-1234-event-20241014",
  "status": "retry",
  "attempt": 3,
  "response_status": 502,
  "delivered_at": null
}

Sertakan audit trail berupa:

  • Timestamp pengiriman pertama dan terakhir.
  • Payload hash untuk membandingkan payload asli dan retry.
  • Indikator apakah response penerima sudah di-acknowledge.

Audit seperti ini memudahkan debugging ketika penerima mengklaim tidak menerima event atau memproses duplikat.

Monitoring Delivery: Retry Metrics dan Dead-Letter Queue

Monitoring membantu mendeteksi pola kegagalan sebelum berdampak lebih luas. Beberapa metrik penting:

  • Retry count per idempotent key: jika terus meningkat, berarti penerima konsisten gagal.
  • Rate of 5xx responses: ukur dari webhook receiver.
  • Dead-letter queue queue size: menunjukkan payload gagal setelah retry maksimal.

Dead-letter queue harus memuat payload + metadata (seperti jumlah percobaan terakhir dan error response). SIstem ops atau support bisa memeriksa DLQ dan memutuskan apakah perlu retry manual, reprocessing, atau investigasi lebih lanjut.

Untuk visualisasi, gunakan dashboard yang memetakan:

  • Jumlah event yang sukses vs berada di DLQ.
  • Average latency per retry.
  • Pola 429/503 yang berulang.

Kesimpulan

Retry webhook idempoten tidak hanya soal mengulang pengiriman, tapi juga menjaga konsistensi operasi melalui kontrak yang jelas, mekanisme acknowledgement, dan audit mendetail. Dengan rate limit, backoff, logging audit, serta pemantauan metrik retry dan dead-letter queue, integrasi eksternal dapat bertahan terhadap kegagalan sementara tanpa menghasilkan data duplikat atau kehilangan event.