Untuk menjamin bahwa event PostHog OSS selalu diproses sekali saja oleh layanan Anda, kontrak webhook idempoten harus mencakup payload yang tegas, otentikasi signature, penanganan deduplikasi, dan strategi retry/resubmit. Artikel ini mendeskripsikan langkah konkret dari schema validation sampai observability sehingga tim backend bisa mengintegrasikan PostHog via webhook dengan andal.

Langkah-langkah di bawah langsung merujuk repositori posthog-foss sebagai konteks: Anda perlu memahami bagaimana PostHog mengirim event, menyesuaikannya dengan API Anda, dan memastikan contract Anda bisa mendeteksi dan menangani kegagalan dua arah.

Menetapkan Kontrak Payload dan Validasi

Payload Contoh dan Schema yang Konsisten

Kontrak dimulai dari payload JSON yang tetap. Misalnya event dari PostHog biasanya mengandung metadata seperti event, distinct_id, properties, dan timestamp. Tetapkan JSON Schema yang diharapkan:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["event", "distinct_id", "timestamp", "properties", "id"],
  "properties": {
    "event": {"type": "string"},
    "distinct_id": {"type": "string"},
    "timestamp": {"type": "string", "format": "date-time"},
    "properties": {"type": "object"},
    "id": {"type": "string"}
  }
}

Field id harus berasal dari PostHog (misalnya id event di posthog_foss). Simpan schema ini di repo Anda dan validasi setiap body masuk menggunakan library JSON Schema atau validator serupa. Validasi awal mencegah event cacat masuk ke pipeline lebih jauh.

Validasi di Sisi Penerima

Setelah memeriksa struktur, lakukan tipe checking tambahan. Misalnya nilai properties.$created_at harus parsable sebagai timestamp, atau properties.$browser mengikuti enumerasi yang Anda definisikan. Jika event gagal validasi, balas dengan HTTP 400 + body yang menjelaskan properti mana yang rusak. Dokumentasikan respons ini dalam kontrak agar PostHog (atau sistem internal Anda yang menyambungkan ke webhook) bisa tahu kapan perlu meninjau data sumber.

Otentikasi Signature dan Secret Rotation

Webhook tidak boleh terbuka. Gunakan header seperti X-PostHog-Signature yang membawa HMAC-SHA256 atas payload dan timestamp, dengan secret yang hanya diketahui PostHog dan endpoint Anda.

const crypto = require('crypto');
function verifySignature(body, signatureHeader, secret) {
  const computed = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(signatureHeader));
}

Pastikan Anda membaca payload mentah sebelum parser memodifikasi whitespace. Keamanan lebih lanjut: sertakan header T untuk timestamp dan tolak request yang lebih tua dari 5 menit untuk mencegah replay attack. Jika signature gagal, kembalikan 401 tanpa memproses event.

Rotasi secret:

  • Simulasikan rotasi dengan menyimpan daftar secret aktif (primary+secondary) dan coba validasi terhadap keduanya.
  • Gunakan sistem manajemen secret (Vault, AWS Secrets Manager) untuk memperbarui secret tanpa deploy manual.
  • Documentasikan jadwal rotasi dan cara PostHog mengirim secret baru agar tidak ada downtime.

Idempotensi, Deduplikasi, dan Strategi Retry/Resubmit

Idempotensi berarti setiap event hanya diproses sekali walaupun webhook dikirim ulang. PostHog bisa mengirim ulang webhook saat tidak menerima respons 2xx, jadi simpan id event di database fast path (Redis/SQL). Struktur umum:

  1. Terima event, validasi signature dan schema.
  2. Cek cache deduplikasi: jika event.id telah diproses, kembalikan 200 tanpa efek samping.
  3. Jika belum, buat transaction: simpan event.id ke store dedup + proses payload.

Gunakan TTL moderat (misalnya 24 jam) pada dedupe store untuk menghindari pertumbuhan tanpa batas, tetapi pastikan masih melindungi window retry PostHog.

Retry/resubmit:

  • Jika pengolahan gagal karena error sementara (timeout, dependensi down), kirim 5xx agar PostHog mencoba kembali.
  • Gunakan queue internal untuk memroses ulang event dengan exponential backoff jika sistem Anda menerima banyak retry sekaligus.
  • Catat retries di log untuk tiap event agar dapat menganalisis tren kegagalan.

Untuk yang sama sekali tidak bisa diproses (schema broken/invalid), balas 422 dan kirim notifikasi sehingga tim bisa memperbaiki data sumber atau menyesuaikan contract.

Observability dan Debugging

Observability membantu membuktikan kontrak bekerja. Terapkan:

  • Log struktural: catat event.id, distinct_id, dan status pemrosesan. Jaga agar log >= JSON agar bisa dicari dengan cepat.
  • Metrics: hitung rate event masuk, rata-rata latency validasi, jumlah signature failure, dan dedupe hit ratio.
  • Tracing: beri trace context dari header PostHog (jika tersedia) ke log pipeline Anda sehingga Anda bisa melacak path event.

Jika webhook tiba tapi hilang downstream, periksa dedupe store. Jika event ditegaskan sudah diproses tapi tidak muncul di sistem target, cari retry log dan validasi bahwa response 2xx telah dikirim.

Integrasi dengan PostHog OSS dan Repositori Reference

Repositori posthog-foss menyimpan kode backend yang mengirim webhook. Lihat modul posthog/webhooks untuk mengetahui format header, secret management, dan cara event dipicu. Gunakan info ini untuk menyamakan expectation Anda: misalnya, PostHog field $os atau $browser bisa berubah; kontrak Anda harus mendokumentasikan nilai minimum yang Anda butuhkan.

Tutup dengan checklist penerapan:

  • Documentasikan schema dan respons error.
  • Konfigurasikan signature validation + secret rotation.
  • Simpan event.id untuk idempotensi dan tangani retry.
  • Pasang metrics/logging untuk observability.
  • Telusuri repositori PostHog OSS bila ada perubahan payload.

Dengan kontrak seperti ini, tim backend Anda bisa menerima event PostHog OSS secara dapat diprediksi dan aman, bahkan saat jaringan atau sistem target mengalami gangguan.