Webhook Status Codes: Panduan Lengkap Response HTTP

Webhook status codes adalah kode respons standar HTTP yang dikirimkan oleh server penerima (receiver) kepada server pengirim (sender) sebagai konfirmasi status pemrosesan sebuah event webhook. Memahami kode-kode ini sangat krusial untuk memastikan keandalan pengiriman data antar-aplikasi, mendeteksi kegagalan integrasi secara dini, dan merancang mekanisme retry (coba ulang) yang efektif.

Setiap kali event terjadi pada platform sumber (seperti pembayaran diterima, pengguna baru mendaftar, atau pesanan dikirim), platform tersebut akan melakukan HTTP POST ke URL tujuan Anda. Respons yang diberikan oleh server Anda menentukan apakah pengiriman tersebut dianggap sukses atau gagal oleh sistem sumber.

Daftar Kategori Webhook Status Codes

Kode status HTTP dibagi menjadi lima kelas utama berdasarkan rentang angka tiga digit. Dalam konteks webhook, berikut adalah interpretasi dari masing-masing kategori:

Rincian Status Code yang Sering Ditemui

1. Status 200 OK (dan 201 Created / 204 No Content)

Ini adalah respons ideal yang wajib dikembalikan oleh server Anda. Kode 200 OK atau 204 No Content memberitahu sistem pengirim bahwa webhook telah sukses diterima, divalidasi, dan dimasukkan ke dalam antrean pemrosesan atau langsung dieksekusi. Sebaiknya kembalikan respons ini secepat mungkin sebelum menjalankan proses berat di latar belakang (background worker).

2. Status 400 Bad Request

Kode ini muncul ketika payload yang dikirimkan tidak sesuai dengan format yang diharapkan, atau header tanda tangan (signature) gagal diverifikasi. Sistem pengirim biasanya tidak akan mencoba mengirim ulang payload yang sama sampai Anda memperbaiki endpoint atau logika validasinya.

3. Status 401 Unauthorized / 403 Forbidden

Menandakan kegagalan otentikasi. Token rahasia, kunci API, atau tanda tangan HMAC (Hash-based Message Authentication Code) yang dikirimkan tidak cocok dengan yang disimpan di server penerima. Periksa kembali konfigurasi kredensial pada dashboard layanan pengirim.

4. Status 404 Not Found

URL endpoint webhook yang Anda daftarkan di sistem sumber salah atau sudah dihapus. Pastikan route pada aplikasi Anda sudah aktif dan dapat diakses publik (jika menggunakan server lokal, pastikan menggunakan alat seperti ngrok untuk pengujian).

5. Status 500 Internal Server Error

Terjadi kesalahan fatal pada kode server Anda, seperti kegagalan koneksi database, pengecualian (exception) yang tidak ditangani, atau kehabisan memori. Sistem pengirim akan mendeteksi ini sebagai kegagalan sementara dan akan menjadwalkan pengiriman ulang (retry).

Praktik Terbaik Penanganan Webhook (Best Practices)

• Respons Cepat: Kirimkan status 200 OK dalam kurun waktu kurang dari 3 detik. Jika proses bisnis Anda memakan waktu lama, gunakan sistem antrean (queue) seperti Redis, RabbitMQ, atau AWS SQS di latar belakang.
• Idempotensi (Idempotency): Sistem sumber terkadang mengirimkan event yang sama dua kali akibat timeout jaringan. Pastikan sistem Anda mampu mengenali ID event yang sama agar tidak terjadi duplikasi data (misalnya duplikasi transaksi pembayaran).
• Verifikasi Tanda Tangan: Selalu validasi header tanda tangan kriptografi sebelum memproses data untuk menghindari serangan pemalsuan webhook (webhook spoofing).
• Log Aktivitas: Simpan semua payload masuk beserta status kodenya ke dalam database atau sistem log (seperti Sentry atau Datadog) untuk memudahkan proses audit dan debugging.

// Contoh Implementasi Express.js untuk Webhook Receiver
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook-endpoint', (req, res) => {
  const event = req.body;

  // 1. Verifikasi signature di sini
  // if (!isValidSignature(req)) { return res.status(401).send('Invalid signature'); }

  // 2. Kirim respons sukses segera ke pengirim
  res.status(200).send({ status: 'received' });

  // 3. Proses data secara asynchronous di latar belakang
  processEventInBackground(event);
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Troubleshooting Kegagalan Webhook

Jika Anda mendapati webhook sering gagal menerima respons 200, lakukan langkah pemeriksaan berikut:

1. Periksa apakah firewall atau aturan Cloudflare memblokir permintaan dari IP address layanan pengirim.
2. Pastikan endpoint Anda menggunakan HTTPS dengan sertifikat SSL/TLS yang valid dan tidak kadaluarsa.
3. Gunakan fitur 'Resend' atau 'Test Webhook' yang biasanya disediakan pada dashboard aplikasi sumber (seperti Midtrans, Stripe, atau GitHub) untuk melihat riwayat respons secara detail.