Panduan Webhook dan Real-time Sync Antar Aplikasi: Implementasi Praktis untuk SIMRS, ERP, dan POS

Bayangkan Anda mengelola SIMRS di Yogyakarta yang terintegrasi dengan BPJS dan SatuSehat. Setiap ada pasien baru, data harus masuk ke sistem antrian, farmasi, dan billing secara real-time. Jika masih mengandalkan polling manual atau sync harian, keterlambatan 5 menit saja bisa menyebabkan antrian menumpuk dan klaim BPJS tertunda. Inilah masalah yang diselesaikan oleh webhook dan real-time sync. Webhook memungkinkan aplikasi Anda mengirim notifikasi ke sistem lain saat ada event, sedangkan real-time sync memastikan data tetap konsisten di semua layanan. Artikel ini akan memandu Anda membangun infrastruktur tersebut dengan pendekatan praktis, mulai dari desain arsitektur, implementasi kode menggunakan Node.js 20 dan Express 4, hingga best practices yang sudah terbukti di lapangan.

1. Memahami Webhook dan Real-time Sync: Konsep Dasar

Webhook adalah mekanisme komunikasi satu arah di mana sebuah aplikasi mengirim HTTP POST ke URL yang sudah ditentukan ketika suatu event terjadi. Berbeda dengan polling di mana klien terus-menerus menanyakan status, webhook bersifat event-driven sehingga lebih efisien. Contoh nyata: ketika pasien mendaftar di SIMRS, sistem langsung mengirim webhook ke modul farmasi untuk menyiapkan resep, ke modul billing untuk membuat tagihan, dan ke aplikasi mobile antrian. Real-time sync adalah konsep yang lebih luas, mencakup sinkronisasi data dua arah atau multi-arah dengan latensi rendah. Webhook sering menjadi tulang punggung real-time sync, namun bisa juga dikombinasikan dengan WebSocket atau message queue seperti RabbitMQ atau Redis Pub/Sub.

Untuk membangun sistem yang andal, Anda perlu memilih arsitektur yang tepat. Ada tiga pola umum: (1) Direct webhook — pengirim langsung memanggil URL penerima. Cocok untuk integrasi sederhana dengan volume rendah. (2) Webhook dengan retry queue — pengirim menyimpan event di queue (misalnya Redis atau RabbitMQ) lalu worker mengirim ulang jika gagal. (3) Event bus — menggunakan broker seperti Kafka atau NATS untuk mendistribusikan event ke banyak konsumen. Untuk skala klinik atau rumah sakit tipe C, pola kedua sudah cukup. Untuk jaringan rumah sakit besar dengan puluhan modul, event bus lebih scalable.

Pertimbangan penting lainnya adalah format payload. Gunakan JSON dengan skema yang jelas, misalnya { "event": "patient.registered", "timestamp": "2025-04-10T08:00:00Z", "data": { ... } }. Sertakan header X-Webhook-Signature untuk verifikasi keaslian. Anda juga perlu menentukan kebijakan idempotency: setiap event memiliki ID unik sehingga penerima dapat mengabaikan duplikat. Ini krusial saat terjadi retry.

2. Implementasi Webhook Receiver dengan Node.js dan Express

Mari kita bangun contoh nyata: sebuah endpoint webhook di SIMRS untuk menerima event pendaftaran pasien dari aplikasi pendaftaran online. Kita akan menggunakan Node.js 20, Express 4.18, dan PostgreSQL 15 sebagai database. Pastikan Anda sudah menginstal dependensi: npm install express body-parser pg crypto. Simpan secret key di environment variable.

Berikut kode minimal untuk menerima webhook, memverifikasi signature, dan menyimpan event ke database:

const express = require('express');
const crypto = require('crypto');
const { Pool } = require('pg');
const app = express();
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/patient', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const expected = crypto.createHmac('sha256', SECRET).update(req.rawBody).digest('hex');
  if (signature !== expected) return res.status(401).send('Invalid signature');
  const { event, data } = req.body;
  await pool.query('INSERT INTO webhook_events (event_id, payload) VALUES ($1, $2) ON CONFLICT DO NOTHING', [data.id, req.body]);
  res.status(200).json({ status: 'received' });
});
app.listen(3000, () => console.log('Webhook receiver running on port 3000'));

Penjelasan: express.json() dengan verify menyimpan raw body untuk verifikasi signature. Kita menggunakan HMAC SHA-256. Setelah signature valid, event disimpan ke tabel webhook_events dengan ON CONFLICT DO NOTHING untuk mencegah duplikasi. Selanjutnya, Anda bisa memproses event ini secara asinkron menggunakan worker terpisah. Pola ini memisahkan penerimaan dan pemrosesan sehingga endpoint tetap responsif.

Untuk real-time sync, setelah event tersimpan, Anda bisa memicu proses lain seperti update stok obat di farmasi atau kirim notifikasi ke antrian. Gunakan message queue seperti Redis Pub/Sub atau RabbitMQ untuk mendistribusikan event ke modul-modul terkait. Contoh: setelah event patient.registered masuk, worker akan memanggil API farmasi untuk memeriksa ketersediaan obat, lalu mengirim push notification ke aplikasi mobile. Semua ini terjadi dalam hitungan detik.

3. Sinkronisasi Dua Arah dan Penanganan Konflik

Dalam banyak kasus, Anda tidak hanya menerima webhook tetapi juga perlu mengirim data ke sistem lain. Misalnya, ketika stok obat di POS pharmacy berubah, SIMRS harus segera mengetahui. Di sinilah sinkronisasi dua arah diperlukan. Anda bisa membangun webhook sender yang memanggil endpoint mitra, atau menggunakan pendekatan change data capture (CDC) dengan Debezium dan Kafka. Untuk skala kecil, webhook sender sudah memadai.

Konflik data bisa terjadi jika dua sistem mengubah data yang sama secara bersamaan. Solusinya adalah menggunakan last-write-wins dengan timestamp, atau versioning seperti ETag. Contoh: setiap record memiliki kolom version yang bertambah setiap update. Ketika menerima update, bandingkan versi; jika versi yang diterima lebih rendah, tolak. Ini mencegah overwrite data yang tidak diinginkan. Untuk aplikasi ERP poultry, konflik bisa terjadi pada stok pakan; gunakan optimistic locking dengan PostgreSQL UPDATE ... WHERE version = $1.

Selain itu, penting untuk memiliki mekanisme dead letter queue (DLQ) untuk event yang gagal diproses setelah beberapa kali retry. Misalnya, setelah 5 kali gagal, event dipindahkan ke tabel failed_events untuk diperiksa manual. Ini menghindari kehilangan data dan memudahkan debugging. Anda juga perlu memonitor latency dan throughput webhook. Tools seperti Prometheus dan Grafana dapat membantu.

Best Practices

1. Gunakan signature HMAC dan timestamp untuk memverifikasi keaslian webhook, serta tolak request yang lebih tua dari 5 menit untuk mencegah replay attack.
2. Terapkan idempotency key pada setiap event dan simpan di database dengan unique constraint untuk menghindari duplikasi saat retry.
3. Pisahkan endpoint penerima dan worker pemroses — terima webhook dengan cepat (200 OK) lalu proses secara asinkron melalui queue untuk menjaga responsivitas.
4. Rancang skema retry eksponensial (misal 1s, 5s, 30s, 5m) dan batasi jumlah percobaan, lalu kirim ke DLQ jika tetap gagal.
5. Monitoring dan logging terpusat — catat setiap event masuk, status pemrosesan, dan error. Gunakan ELK Stack atau Grafana Loki untuk analisis.

FAQ

Apa perbedaan webhook dan API biasa?

API biasa bersifat pull (klien meminta data), sedangkan webhook bersifat push (server mengirim data saat event terjadi). Webhook lebih efisien untuk notifikasi real-time karena tidak perlu polling.

Bagaimana jika penerima webhook sedang down?

Pengirim harus memiliki mekanisme retry dengan exponential backoff. Jika tetap gagal setelah beberapa kali, simpan event di dead letter queue untuk diproses ulang secara manual atau terjadwal.

Apakah webhook aman untuk data medis?

Ya, asalkan menggunakan HTTPS, signature HMAC, dan enkripsi payload jika perlu. Untuk data sensitif, pertimbangkan enkripsi end-to-end atau gunakan VPN khusus.

Bisakah webhook digunakan untuk sinkronisasi dua arah?

Bisa. Anda perlu membangun webhook sender di kedua sisi, plus mekanisme penanganan konflik seperti versioning atau timestamp. Untuk kompleksitas tinggi, gunakan message broker seperti Kafka.

Membangun webhook dan real-time sync yang andal membutuhkan perencanaan matang, mulai dari desain event, keamanan, hingga penanganan kegagalan. Jika Anda mengelola SIMRS, SIM Klinik, ERP, atau POS di Yogyakarta, Magelang, atau DIY, dan ingin mengintegrasikan sistem secara real-time, tim kami siap membantu. Kami menyediakan layanan konsultasi IT dan pengembangan aplikasi yang disesuaikan dengan kebutuhan Anda. Hubungi kami untuk audit integrasi dan implementasi webhook yang skalabel.