Dalam kontrak API webhook, tujuan utama adalah memastikan penerima tidak memproses peristiwa yang sama lebih dari sekali sekaligus tetap bisa menangani retry dari pengirim. Artikel ini langsung menjelaskan bagaimana mendesain autentikasi signature/token rotasi, payload eksplisit, idempoten, pola retry, penanganan error transient vs. permanent, serta observabilitas yang dibutuhkan.

1. Autentikasi dan Validasi Mutlak

Autentikasi memastikan hanya pengirim resmi yang dapat memanggil webhook. Kontrak harus menetapkan metode secara eksplisit.

Signature HMAC

Minta pengirim menandatangani payload dengan shared secret dan sertakan header seperti X-Webhook-Signature. Penerima harus menghitung HMAC dari isi raw body dan membandingkannya. Jangan melakukan parsing JSON sebelum verifikasi karena perubahan whitespace akan mengubah signature.

Token Rotasi

Sediakan endpoint untuk rotasi token dan pastikan kontrak mendefinisikan header validasi token (misal Authorization: Bearer <token>) dan masa berlaku token yang wajar. Jika token disusupi, rotasi cepat akan membatasi dampak.

2. Struktur Payload dan Response yang Eksplisit

Payload harus mencakup informasi minimum untuk proses idempoten dan audit.

{
  "event_id": "evt-12345",
  "resource": "payment",
  "action": "confirmed",
  "timestamp": "2024-10-05T09:30:00Z",
  "data": {
    "payment_id": "pay-abc",
    "amount": 45000,
    "status": "COMPLETED"
  }
}

Field event_id unik per event untuk deduplikasi. resource dan action menjelaskan konteks, sementara data adalah payload domain.

Untuk response, sediakan kode HTTP dan body yang konsisten:

  • 200 OK untuk berhasil, dengan body konfirmasi sederhana.
  • 202 Accepted untuk proses asynchronous sehingga pengirim tahu proses masih berjalan.
  • 4xx untuk kesalahan penerima seperti payload invalid.
  • 5xx untuk error transient di penerima.
{
  "status": "accepted",
  "received_at": "2024-10-05T09:30:05Z",
  "processed_event": "evt-12345"
}

3. Menjaga Idempoten

Idempoten mencegah efek ganda bila webhook dipanggil ulang. Kontrak harus menyertakan mekanisme deduplikasi.

Dedupe Key

Simpan event_id terakhir yang diproses untuk setiap resource/action dan abaikan duplicate. Catat timestamp supaya dapat menghapus cache setelah window tertentu.

Status Resource

Alih-alih melakukan tindakan yang mutatif tanpa kondisi, periksa status resource. Misalnya jika status pembayaran sudah COMPLETED, abaikan update kedua dan jawab 200 OK agar pengirim berhenti retry.

4. Pola Retry dan Handling Error

Kontrak harus menjelaskan kapan webhook sender boleh retry dan kapan harus menghentikan.

Retry Otomatis vs Manual

Definisikan algoritma retry: logika exponential backoff dengan batas maksimal percobaan. Kontrak juga harus menyediakan header atau body response yang menyatakan apakah retry diizinkan.

Contoh: jika penerima sedang maintenance, jawab 503 Service Unavailable plus body {"retry_after": 30}. Pengirim otomatis mencoba lagi setelah delay. Untuk error permanent seperti payload invalid, kirim 422 Unprocessable Entity dan jangan retry.

Error Transient vs Permanent

Berikan daftar error yang dianggap transient (misalnya timeout database, dependency unavailable) dan permanent (schema mismatch, invalid signature). Gunakan log level berbeda untuk analisis.

5. Observabilitas dan Keandalan

Monitoring webhook sangat penting untuk menilai kesehatan kontrak.

  • Log: catat event_id, hasil signature, decision idempoten, dan status response.
  • Metric: hitung jumlah retry, rate error 4xx/5xx, dan latency.
  • Dead-letter: event yang gagal setelah batas retry harus dikirim ke antrean dead-letter untuk investigasi manual.

Perhatikan juga alert untuk spikes 5xx agar segera ditindak.

6. Checklist Verifikasi Integrasi

  • Apakah signature/token diverifikasi sebelum parsing payload?
  • Apakah event_id unik dan digunakan untuk deduplikasi?
  • Apakah response konsisten dengan kode HTTP yang benar?
  • Apakah retry hanya diizinkan untuk error transient dan dijelaskan di kontrak?
  • Apakah status resource dievaluasi untuk menghindari side effect ganda?
  • Apakah terdapat logging, metric, dan dead-letter untuk observabilitas?
  • Apakah ada rencana rotasi token dan mekanisme audit?

Dengan kontrak yang eksplisit dan checklist ini, webhook menjadi lebih tahan gagal, aman, dan mudah di-debug saat terjadi insiden.