Mengintegrasikan webhook provider dengan pipeline deteksi anomali berbasis Large Language Model (LLM) menghadirkan tantangan stabilitas sistem. Latensi inferensi LLM yang bervariasi (seringkali melampaui rentang 2 hingga 10 detik) dapat memicu timeout pada webhook sender. Ketika sender melakukan automatic retry, sistem penerima rentan mengalami pemrosesan ganda (duplicate execution), lonjakan biaya token, dan cascade failure akibat batas kuota token rate-limiting (TPM/RPM).

Untuk membangun receiver yang aman dan tangguh, arsitektur harus memisahkan proses ingestion dari eksekusi model menggunakan state idempotensi berbasis Redis, pengamanan payload melalui signature verification, serta proteksi dependensi downstream menggunakan pola Circuit Breaker.

Tantangan Arsitektur Webhook Anomaly LLM

Pola pemrosesan webhook konvensional yang bersifat sinkron langsung terancam gagal ketika diterapkan pada integrasi model bahasa besar:

  • Latensi Tidak Deterministik: Waktu respons LLM bervariasi tergantung panjang konteks, beban cluster provider, dan ukuran token output. Sebagian besar webhook dispatcher memutus koneksi jika respons HTTP tidak diterima dalam rentang 3–5 detik.
  • Retry Storm & Pemrosesan Ganda: Sender mengasumsikan paket hilang saat koneksi timeout, lalu mengirim ulang event identik berkali-kali. Tanpa kontrol status, model AI akan menganalisis anomali yang sama berulang kali.
  • Penipisan Kuota API (Rate Limit Cascade): Ketika permintaan duplikat melonjak, upstream LLM provider akan mengembalikan HTTP 429 (Too Many Requests). Kegagalan ini menyebar ke antrean pemrosesan lokal dan berisiko menjatuhkan seluruh worker.

Verifikasi Keamanan: HMAC Signature

Sebelum memproses payload atau mengalokasikan resource Redis dan LLM, validasi integritas data wajib dilakukan pada layer HTTP boundary. Gunakan perbandingan hmac.compare_digest untuk mencegah timing attacks.

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header:
        return False
    expected_signature = hmac.new(
        key=secret.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, signature_header)

Pola Idempotensi dengan Redis

Idempotensi memastikan bahwa satu event log hanya dianalisis satu kali, terlepas dari berapa kali sender mengirimkan ulang webhook tersebut. Pendekatan standar memanfaatkan header Idempotency-Key atau hashing deterministik dari payload body jika ID unik tidak disediakan oleh provider.

Gunakan perintah atomik Redis SET resource_key value NX EX ttl untuk mengamankan lock eksekusi:

  1. Acquire Lock (State: PROCESSING): Jika kunci belum ada, set status menjadi PROCESSING dengan TTL singkat (misal: 60 detik) untuk mengantisipasi node worker crash mendadak.
  2. Sudah Ada (Cache Hit): Jika kunci sudah ada dengan state COMPLETED, segera kembalikan respons tersimpan (HTTP 200 OK) tanpa menjalankan inferensi LLM. Jika state masih PROCESSING, kembalikan HTTP 202 Accepted untuk memberi sinyal sender agar menunggu.
  3. Finalisasi (State: COMPLETED): Simpan hasil inferensi anomali dan perpanjang TTL (misal: 24 jam) agar retry berikutnya menerima respons instan.

Pola Circuit Breaker untuk Dependensi LLM

Circuit Breaker membungkus pemanggilan eksternal ke provider LLM (seperti OpenAI, Anthropic, atau self-hosted vLLM). Circuit memiliki tiga state:

  • CLOSED: Kondisi normal. Panggilan diteruskan langsung ke LLM. Kegagalan (error 5xx atau timeout) dicatat.
  • OPEN: Jika ambang batas kegagalan terlampaui dalam jendela waktu tertentu, circuit terbuka. Semua panggilan masuk langsung digagalkan secara lokal atau dialihkan ke model heuristik darurat (rule-based anomaly detector) tanpa membebani LLM downstream.
  • HALF-OPEN: Setelah durasi cooldown berakhir, sejumlah kecil permintaan diizinkan lewat untuk menguji apakah dependensi LLM sudah pulih.

Implementasi Lengkap: FastAPI, Redis, & PyBreaker

Berikut implementasi endpoint receiver webhook menggunakan Python, FastAPI, Redis, dan pustaka pybreaker:

import json
from fastapi import FastAPI, Request, HTTPException, Header, Response, status
import redis
import pybreaker
import httpx

app = FastAPI()
redis_client = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)
WEBHOOK_SECRET = "production_shared_secret_key"

# Konfigurasi Circuit Breaker: Buka circuit jika 3 kegagalan beruntun, reset timeout 30 detik
llm_breaker = pybreaker.CircuitBreaker(fail_max=3, reset_timeout=30)

@llm_breaker
def call_llm_anomaly_model(anomaly_payload: dict) -> dict:
    # Simulasi eksekusi downstream LLM API dengan hard timeout
    with httpx.Client(timeout=4.0) as client:
        # ponytail: ganti url mock dengan production LLM endpoint
        response = client.post(
            "https://api.openai.com/v1/chat/completions",
            headers={"Authorization": "Bearer sk-placeholder"},
            json={
                "model": "gpt-4o-mini",
                "messages": [
                    {"role": "system", "content": "Analyze telemetry for anomalies. Respond in JSON."},
                    {"role": "user", "content": json.dumps(anomaly_payload)}
                ]
            }
        )
        response.raise_for_status()
        return response.json()

def fallback_heuristic_analyzer(anomaly_payload: dict) -> dict:
    # Failover lokal saat circuit breaker LLM berstatus OPEN
    return {
        "status": "fallback_rule_triggered",
        "is_anomaly": anomaly_payload.get("metrics", {}).get("error_rate", 0) > 0.05,
        "source": "local_heuristic_engine"
    }

@app.post("/api/v1/webhook/anomaly")
async def receive_anomaly_webhook(
    request: Request,
    response: Response,
    x_idempotency_key: str = Header(None),
    x_signature_sha256: str = Header(None)
):
    body_bytes = await request.body()

    # 1. Validasi Keamanan Signature
    if not verify_webhook_signature(body_bytes, x_signature_sha256, WEBHOOK_SECRET):
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid signature")

    if not x_idempotency_key:
        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Missing Idempotency-Key header")

    idempotency_store_key = f"idempotency:anomaly:{x_idempotency_key}"

    # 2. Pola Idempotensi: Distributed Lock via Redis SET NX
    is_new = redis_client.set(idempotency_store_key, json.dumps({"state": "PROCESSING"}), nx=True, ex=60)
    
    if not is_new:
        cached_data = json.loads(redis_client.get(idempotency_store_key))
        if cached_data.get("state") == "PROCESSING":
            response.status_code = status.HTTP_202_ACCEPTED
            return {"message": "Event is currently being evaluated."}
        # Return state COMPLETED yang telah dicache sebelumnya
        return {"message": "Event previously processed", "result": cached_data.get("result")}

    payload = await request.json()

    # 3. Eksekusi Proteksi dengan Circuit Breaker
    try:
        try:
            analysis_result = call_llm_anomaly_model(payload)
        except pybreaker.CircuitBreakerError:
            # Circuit OPEN: failover tanpa memutus webhook ingestion
            analysis_result = fallback_heuristic_analyzer(payload)

        # 4. Finalisasi Status Idempotensi
        redis_client.set(
            idempotency_store_key,
            json.dumps({"state": "COMPLETED", "result": analysis_result}),
            ex=86400 # 24 jam cache
        )
        return {"status": "processed", "data": analysis_result}

    except Exception as exc:
        # Hapus lock idempotensi jika terjadi error internal tak tertangani agar dapat diretry
        redis_client.delete(idempotency_store_key)
        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc))

Catatan: Pada implementasi sistem berskala tinggi dengan volume webhook ribuan request per detik, pindahkan pemanggilan model LLM ke antrean background asynchronous (seperti Celery, ARQ, atau RabbitMQ/Kafka). Kembalikan respons HTTP 202 Accepted ke sender segera setelah idempotency lock berhasil dicatat di Redis.

Ringkasan Trade-Off

PendekatanKelebihanKonsekuensi / Trade-off
Redis SET NX IdempotencyMenghilangkan eksekusi LLM berulang; hemat biaya token dan alokasi compute.Membutuhkan Redis berkonfigurasi high-availability. Jika TTL terlalu singkat, replay dapat lolos.
Circuit BreakerMencegah cascade failure dan blocking worker saat model AI mengalami rate-limit.Memerlukan logika failover/fallback memadai (seperti aturan statis) saat sirkuit terbuka.
Synchronous ProcessingArsitektur sederhana; payload dan respons langsung selesai dalam 1 request.Batas timeout sender ketat. Hanya cocok untuk LLM berlatensi rendah atau skenario beban rendah.