Kontrak API Webhook yang Andal untuk Blogging dengan LLM

Asisten blogging berbasis LLM membutuhkan webhook yang dapat diandalkan untuk menerima instruksi, status publikasi, atau umpan balik pengguna. Kontrak API webhook menentukan bagaimana LLM mengirim payload, bagaimana Anda memvalidasi data, dan bagaimana sistem backend menangani kegagalan tanpa menyebabkan duplikat atau kehilangan pesan. Artikel ini langsung menjelaskan komponen utama kontrak tersebut, mulai dari autentikasi hingga observabilitas, agar integrasi tetap aman dan dapat di-debug.

1. Mendefinisikan Payload dan Validasi Schema

Kontrak dimulai dengan payload yang dipahami kedua belah pihak. Terapkan schema JSON yang eksplisit untuk konten posting, metadata, dan status pengiriman. Contoh payload:

{
  "post_id": "blog-2026-llm",
  "status": "ready_for_review",
  "summary": "Draft awal artikel tentang integrasi webhook",
  "metadata": {
    "language": "id",
    "model_version": "gpt-5.1"
  }
}

Validasi schema dengan library seperti Ajv (Node.js) atau jsonschema (Python) di sisi penerima mencegah runtime error akibat field hilang atau tipe tidak sesuai. Selalu tanggapi dengan 400 Bad Request jika payload tidak valid, dan sertakan pesan kesalahan yang membantu LLM memperbaiki isi.

Strategi Evolusi Schema

Untuk memungkinkan evolusi schema tanpa gangguan, gunakan versi schema di header (misal X-Contract-Version) dan desain schema agar field baru bersifat optional dengan default. Komunikasikan perubahan schema melalui dokumentasi kontrak dan fallback logika versi lama selama periode migrasi.

2. Autentikasi dan Integritas

Kontrak API webhook harus menetapkan mekanisme autentikasi agar hanya LLM resmi yang dapat mengirim panggilan. Pendekatan umum adalah HMAC signature dengan header yang jelas.

POST /webhooks/llm/callback HTTP/1.1
Host: example.blog
Content-Type: application/json
X-Llm-Signature: sha256=abcdef...

{...payload...}

Server menghitung ulang HMAC menggunakan shared secret dan membandingkan signature. Pastikan timing-safe comparison agar tidak rentan timing attack. Jika secret kadaluwarsa, gunakan rotating secret dengan metadata X-Secret-Version dan fallback ke versi sebelumnya selama grace period.

Jika autentikasi gagal, respons 401 Unauthorized dengan log entry lengkap (tanpa secret) memberi feedback cepat dan mendukung audit.

3. Idempotensi dan Duplicate Delivery

Webhook sering kali dikirim ulang oleh LLM saat tidak menerima respons yang diharapkan. Kontrak harus menetapkan header idempotensi, misalnya X-Webhook-Id, yang unik untuk setiap event. Backend menyimpan ID ini bersama status pemrosesan minimal selama periode retry.

Alur ideal:

  • Terima webhook dengan ID.
  • Periksa jika ID sudah pernah diproses; jika iya, kembalikan 200 OK segera tanpa menjalankan logika domain lagi.
  • Jika belum, jalankan pemrosesan, catat hasil (misal status publish), lalu tandai ID sebagai selesai.

Catatan: jangan hapus ID terlalu cepat agar retry yang datang belakangan masih bisa dikenali—durasi penyimpanan tergantung SLA retry LLM.

4. Retry dan Backoff Terencana

LLM kemungkinan akan retry sesuai kontrak. Tetapkan header atau body yang mengindikasikan bahwa event ini adalah retry ke-n, lalu sesuaikan idempotensi dengan cara di atas. Jangan mengandalkan implementasi assumption bahwa retry sequential atau memiliki delay tetap.

Gunakan strategi backoff eksponensial di sisi pengirim (LLM) bila didesain oleh kontrak, namun di sisi penerima Anda juga harus siap menolak sementara dengan 429 Too Many Requests atau 503 Service Unavailable jika sistem sedang overload. Sertakan header Retry-After untuk memberi sinyal ke LLM kapan mencoba lagi.

Retry Setelah Token Kadaluarsa

Jika webhook gagal karena autentikasi (misal token atau secret kadaluarsa), kembalikan 401 dan log detail. Pada penerima, jangan secara otomatis menandai event sebagai selesai—biarkan LLM retry dengan kredensial baru. Dokumentasikan flow pembaruan token supaya tim LLM memahami kapan harus memperbarui shared secret.

5. Observabilitas dan Logging

Kontrak webhook harus memaksa kedua pihak mencatat metadata penting. Sisi penerima perlu menyimpan:

  • ID event
  • Timestamp penerimaan
  • Signature atau hasil autentikasi (valid/tidak)
  • Status pemrosesan (sukses/gagal + alasan)

Log ini membantu menelusuri kasus duplicate delivery atau imbalance antara postingan dan respons webhook.

Tambahkan structured logging (JSON) agar observability tools bisa menggabungkan data. Telemetri latency (dari penerimaan sampai pemrosesan selesai) membantu memutuskan apakah perlu scaling webhook worker.

6. Mitigasi Edge Case

Delivery yang Terlambat atau Timeout

Kontrak harus menetapkan batas waktu pemrosesan webhook agar LLM tidak menunggu selamanya. Jika operasi domain (misalnya render preview panjang) memerlukan waktu lama, segera tulis event ke queue internal dan kembalikan 202 Accepted, lalu laporkan status asynchronous lewat endpoint status.

Token Kadaluwarsa di Tengah Retry

Jika LLM mengirim ulang tapi token sudah kadaluarsa, gunakan header tambahan seperti X-Auth-Error dalam log untuk melacak. Pastikan sistem Anda dapat membedakan antara retry yang harus diproses ulang dan retry yang perlu menunggu pembaruan kredensial.

Evolusi dan Deprecation

Buat kontrak versi untuk memudahkan migrasi. Jika memutuskan menghapus field, teruskan dukungan versi lama selama minimal satu siklus release, dan sediakan endpoint status untuk menampilkan versi schema aktif.

Kesimpulan

Kontrak API webhook yang andal untuk blogging dengan LLM memetakan respons webhook, autentikasi, idempotensi, retry/backoff, observabilitas, serta mitigasi edge case seperti duplikat atau token kadaluarsa. Dengan schema yang jelas, header khusus (misalnya X-Webhook-Id, X-Llm-Signature, X-Contract-Version), serta logging terstruktur, Anda bisa menjaga aliran data tetap konsisten dan mudah di-debug. Implementasi kontrak ini memperkuat kolaborasi antara LLM dan sistem blogging, sebagaimana dikonsep pada pendekatan “Blogging with an LLM assistant”.