Artikel job queue async membahas cara memproses tugas AI yang lama lewat submit-worker-status. Begitu worker selesai, langkah berikutnya sering berupa memberi tahu sistem lain bahwa hasilnya sudah siap — dan di situlah webhook masuk. Tiga hal yang dibahas di sini: memverifikasi bahwa webhook benar-benar berasal dari pengirim yang sah, mengirim ulang webhook yang gagal terkirim tanpa membuat penerima memproses dua kali, dan kode yang sudah diuji untuk ketiganya.

Kenapa Webhook Butuh Verifikasi Signature

Pola 1: HMAC Signature dengan Timestamp

Pengirim dan penerima berbagi satu secret key. Pengirim menghitung HMAC-SHA256 dari gabungan timestamp dan payload, lalu mengirimkannya sebagai header. Penerima menghitung ulang dengan secret yang sama dan membandingkan — kalau cocok dan timestamp masih segar, payload dianggap sah.

import hmac, hashlib, time

def buat_signature(payload_bytes: bytes, secret: str, timestamp: str) -> str:
    pesan = f"{timestamp}.{payload_bytes.decode()}".encode()
    return hmac.new(secret.encode(), pesan, hashlib.sha256).hexdigest()

def verifikasi_signature(payload_bytes, secret, timestamp, signature_diterima,
                          toleransi_detik=300):
    now = int(time.time())
    if abs(now - int(timestamp)) > toleransi_detik:
        return False, "timestamp kadaluarsa"

    signature_diharapkan = buat_signature(payload_bytes, secret, timestamp)
    if not hmac.compare_digest(signature_diharapkan, signature_diterima):
        return False, "signature tidak cocok"

    return True, "valid"

Dua detail yang sengaja dijaga: hmac.compare_digest dipakai alih-alih operator == biasa, supaya waktu perbandingan tidak bocor informasi tentang seberapa banyak karakter yang sudah cocok (timing attack). Timestamp masuk ke dalam pesan yang di-hash, bukan sekadar dikirim terpisah — kalau signature hanya menghitung hash dari payload saja, penyerang bisa mengambil signature valid yang lama dan memakainya lagi kapan pun tanpa terdeteksi.

Pola 2: Retry dengan Exponential Backoff di Sisi Pengirim

Penerima webhook bisa saja sedang down, lambat, atau timeout sesaat. Pengirim yang baik tidak menyerah di percobaan pertama, tapi juga tidak boleh spam retry tanpa jeda — exponential backoff menaikkan jeda antar percobaan secara bertahap.

def kirim_webhook_dgn_retry(fungsi_kirim, max_percobaan=5, base_delay=1.0):
    riwayat = []
    for percobaan in range(1, max_percobaan + 1):
        try:
            hasil = fungsi_kirim()
            riwayat.append((percobaan, "sukses"))
            return hasil, riwayat
        except GagalSementara as e:
            riwayat.append((percobaan, f"gagal: {e}"))
            if percobaan == max_percobaan:
                raise
            delay = base_delay * (2 ** (percobaan - 1))
            time.sleep(delay)

Pola 3: Idempotensi di Sisi Penerima — Bug yang Paling Sering Terlewat

Konsekuensi dari retry di Pola 2: penerima bisa menerima webhook yang sama persis lebih dari sekali. Ini bisa terjadi bahkan tanpa error sungguhan — penerima berhasil memproses dan mengembalikan 200 OK, tapi response itu hilang di jaringan sebelum sampai ke pengirim, sehingga pengirim mengira gagal dan mengirim ulang. Kalau efek samping webhook itu menambah saldo, mengirim notifikasi, atau memicu pembayaran, dikirim dua kali berarti dijalankan dua kali.

class PenerimaWebhook:
    def __init__(self):
        self.event_terproses = set()  # produksi: UNIQUE(event_id) di DB
        self.saldo_user = {}

    def proses_event(self, event_id, user_id, jumlah_kredit):
        if event_id in self.event_terproses:
            return "diabaikan_duplikat"

        self.saldo_user[user_id] = self.saldo_user.get(user_id, 0) + jumlah_kredit
        self.event_terproses.add(event_id)
        return "diproses"

Endpoint FastAPI Lengkap, Diuji dengan Request HTTP Asli

Menggabungkan signature dan idempotensi jadi satu endpoint, lalu diuji lewat TestClient — yang berarti request benar-benar lewat lapisan ASGI, bukan cuma memanggil fungsi Python secara langsung.

Baca Juga:

Skema Database Riwayat Percakapan AI: Pola dan Query

@app.post("/webhook/hasil-ai")
async def terima_webhook(request: Request):
    payload_bytes = await request.body()
    timestamp = request.headers.get("X-Webhook-Timestamp", "")
    signature = request.headers.get("X-Webhook-Signature", "")

    if not verifikasi(payload_bytes, timestamp, signature):
        raise HTTPException(status_code=401, detail="signature tidak valid")

    data = await request.json()
    event_id = data.get("event_id")

    if event_id in event_terproses:
        return {"status": "diabaikan_duplikat"}

    event_terproses.add(event_id)
    return {"status": "diproses", "job_id": data.get("job_id")}

Alur Lengkap dari Job Selesai sampai Diproses Penerima

1. Worker menyelesaikan job dan menyiapkan payload berisi event_id unik, bukan cuma job_id — event_id mewakili “notifikasi ini”, bisa beda dari job kalau satu job mengirim beberapa notifikasi (progres, lalu selesai).
2. Pengirim menghitung signature HMAC dari timestamp + payload, mengirim POST ke URL webhook dengan header signature dan timestamp.
3. Kalau gagal (timeout, 5xx), pengirim retry dengan exponential backoff, bukan langsung menyerah atau spam tanpa jeda.
4. Penerima memverifikasi signature dan timestamp dulu sebelum membaca isi payload sebagai data yang bisa dipercaya.
5. Penerima mengecek event_id terhadap daftar yang sudah diproses — kalau sudah ada, kembalikan sukses tanpa menjalankan efek samping lagi.

Kapan In-Memory Set Cukup, Kapan Butuh Tabel Database

Pertanyaan yang Sering Muncul

Kesimpulan

Webhook untuk hasil AI async terlihat sederhana di permukaan — kirim POST begitu job selesai — tapi tiga hal yang dibahas di sini adalah yang membedakan implementasi yang aman dari yang rapuh. Verifikasi signature dengan timestamp mencegah payload palsu dan replay attack, teruji lewat empat skenario termasuk percobaan replay yang eksplisit. Retry dengan exponential backoff di sisi pengirim mencegah hasil job hilang begitu saja karena kegagalan sesaat. Dan idempotensi di sisi penerima adalah yang paling sering terlewat justru karena konsekuensinya tidak langsung kelihatan sampai retry benar-benar terjadi — pengujian di atas membuktikan bug double-credit itu nyata, bukan sekadar risiko teoretis.

Artikel terkait: job queue async untuk tugas AI (tautan di bawah) dan skill backend untuk AI engineering.