Webhooks & Event Push — Temuya Docs

Gambaran Umum

Dalam dunia perangkat lunak modern yang bergerak cepat, menunggu adalah hal yang sangat tidak efisien. Meminta data secara berulang-ulang (polling) ke server untuk memeriksa apakah ada perubahan terbaru bukan hanya memboroskan sumber daya komputasi, tetapi juga menyebabkan keterlambatan informasi. Untuk memecahkan kebuntuan ini, Temuya POS menghadirkan fitur Webhooks. Webhooks adalah fondasi dari komunikasi reaktif, memungkinkan sistem kami untuk “berteriak” ke sistem Anda setiap kali ada peristiwa penting yang terjadi, seketika itu juga.

Konsep Webhooks sangat mirip dengan sistem notifikasi push di ponsel pintar Anda. Anda tidak perlu terus-menerus membuka aplikasi pesan untuk melihat apakah ada pesan masuk; aplikasi tersebut akan memberi tahu Anda saat pesan itu tiba. Dalam konteks Temuya POS, Anda sebagai pengembang dapat mendaftarkan sebuah URL tujuan (endpoint) di panel kontrol. Kemudian, Anda memilih jenis kejadian atau event apa saja yang ingin Anda ketahui. Mulai saat itu, setiap kali kejadian tersebut terjadi di toko — misalnya, ada pelanggan yang selesai membayar, atau stok sebuah produk menipis — server kami akan secara otomatis membungkus informasi kejadian tersebut dan mengirimkannya langsung ke URL yang telah Anda daftarkan menggunakan metode HTTP POST.

Fitur Webhooks membuka pintu menuju otomatisasi tanpa batas. Dengan menerima data secara real-time, sistem eksternal Anda dapat langsung memicu berbagai tindakan lanjutan, seperti mengirim email ucapan terima kasih kepada pelanggan, memperbarui dasbor analitik kustom, atau memesan stok baru secara otomatis ke distributor. Webhooks menjadikan arsitektur integrasi Anda lebih elegan, efisien, dan responsif terhadap dinamika bisnis yang terus berubah.

Skenario Bisnis Nyata

Mari kita cermati operasional “Kopi Senja”, sebuah jaringan kedai kopi populer yang menggunakan Temuya POS. Kopi Senja memiliki program loyalitas pelanggan yang sangat sukses, di mana pelanggan mengumpulkan poin untuk setiap cangkir kopi yang mereka beli. Namun, sistem poin ini dikelola oleh aplikasi pihak ketiga yang terpisah dari POS.

Sebelum menggunakan Webhooks, sistem loyalitas tersebut harus terus-menerus bertanya kepada server Temuya POS setiap lima menit: “Apakah ada transaksi baru?”. Cara ini lambat, membebani server, dan membuat pelanggan sering kali harus menunggu sebelum poin mereka diperbarui di aplikasi seluler.

Tim pengembang Kopi Senja kemudian beralih menggunakan Webhooks Temuya POS. Mereka mendaftarkan URL endpoint sistem loyalitas mereka dan berlangganan pada event transaction.created. Sekarang, setiap kali seorang barista Kopi Senja menyelesaikan transaksi di mesin kasir Temuya POS, sistem backend Temuya akan secara instan (dalam hitungan milidetik) menembakkan data transaksi tersebut — lengkap dengan daftar minuman yang dibeli, total harga, dan nomor keanggotaan pelanggan — langsung ke URL sistem loyalitas.

Sistem loyalitas menerima data ini, langsung mengkalkulasi poin yang didapat, dan dalam hitungan detik, aplikasi seluler pelanggan akan berbunyi ping dengan notifikasi: “Selamat! Anda mendapatkan 50 poin dari pembelian Anda di Kopi Senja.” Pengalaman pelanggan menjadi jauh lebih mulus, server bekerja lebih efisien tanpa polling yang tidak perlu, dan manajemen Kopi Senja dapat tersenyum puas melihat integrasi yang berjalan sempurna. Selain itu, mereka juga berlangganan event stock.low agar manajer gudang langsung mendapat notifikasi Telegram otomatis setiap kali stok susu mulai menipis.

Alur Kerja

Diagram di bawah ini mengilustrasikan alur perjalanan sebuah event mulai dari pemicunya di Temuya POS hingga berhasil diterima dan diverifikasi oleh sistem eksternal milik pengembang.

sequenceDiagram
    autonumber
    actor Kasir as Pengguna / Kasir (Aplikasi POS)
    participant CoreAPI as Hono API Backend
    participant EventQueue as Antrean Background Task (Queue)
    participant WebhookWorker as Worker Pengirim Webhook
    participant SistemEksternal as Endpoint Penerima Eksternal

    Kasir->>CoreAPI: Menyelesaikan Transaksi Pembayaran
    CoreAPI->>CoreAPI: Menyimpan Transaksi ke Database
    CoreAPI->>EventQueue: Memasukkan Event 'transaction.created' ke Antrean
    CoreAPI-->>Kasir: Response Transaksi Sukses
    
    note over EventQueue,WebhookWorker: Proses Asinkron di Latar Belakang
    
    EventQueue->>WebhookWorker: Mengambil Pekerjaan Webhook
    WebhookWorker->>WebhookWorker: Merakit Payload JSON & Membuat Signature HMAC
    WebhookWorker->>SistemEksternal: HTTP POST Request (Payload + Header X-Hub-Signature)
    
    alt Endpoint Tidak Merespons / Error (500, Timeout)
        SistemEksternal-->>WebhookWorker: Error Response atau Timeout
        WebhookWorker->>EventQueue: Menjadwalkan Ulang (Retry dengan Exponential Backoff)
    else Endpoint Merespons Sukses (200 OK)
        SistemEksternal->>SistemEksternal: Memvalidasi Signature HMAC
        SistemEksternal->>SistemEksternal: Memproses Data Transaksi
        SistemEksternal-->>WebhookWorker: Response HTTP 200 OK
        WebhookWorker->>WebhookWorker: Menandai Pekerjaan Selesai
    end

Teknologi & Infrastruktur

Pengiriman Webhooks di Temuya POS dibangun dengan prinsip keandalan tinggi dan pemrosesan asinkron agar tidak pernah menghambat kinerja sistem kasir utama.

Komponen Fitur	Penjelasan Teknis	Peran dalam Ekosistem
Pendaftaran Webhook	Panel UI Developer / API Manajemen	Tempat di mana pengembang memasukkan URL tujuan dan memilih event yang diminati. Menghasilkan Secret Key unik untuk keamanan.
Payload Data JSON	Format Standar Komunikasi	Setiap event dikirimkan dalam format JSON terstruktur yang berisi ID kejadian, tipe kejadian, waktu, dan objek data yang relevan.
Sistem Antrean (Queue)	Background Jobs (Cloudflare Queues/Workers)	Memisahkan proses bisnis utama dari pengiriman jaringan, memastikan POS tetap cepat meskipun server penerima webhook sedang lambat atau mati.
Keamanan HMAC SHA-256	Header `X-Temuya-Signature`	Sistem akan memverifikasi integritas data dan memalsukan asal-usul payload menggunakan hash kriptografis berdasarkan Secret Key yang disepakati.
Mekanisme Retry	Exponential Backoff Strategy	Jika server Anda gagal merespons, sistem kami akan mencoba mengirim ulang webhook beberapa kali dengan jeda waktu yang semakin memanjang untuk mencegah sistem kewalahan.

Keterkaitan dengan Fitur Lain

Webhooks adalah pilar penting dalam arsitektur integrasi, bekerja harmonis dengan berbagai komponen lain:

API Keys (Kunci API): Jika Webhooks adalah cara Temuya POS “berbicara” kepada Anda, maka Kunci API adalah cara Anda “berbicara” kembali kepada Temuya POS. Seringkali, sebuah sistem menerima webhook tentang transaksi baru, lalu menggunakan Kunci API untuk memanggil endpoint Temuya guna mengambil rincian lebih detail mengenai pelanggan pada transaksi tersebut.
Sistem Notifikasi & Alert: Beberapa kejadian yang memicu webhook (seperti stok menipis) juga sering kali memicu notifikasi visual (bel) di dalam antarmuka aplikasi Temuya POS itu sendiri, memastikan bahwa baik sistem eksternal maupun manusia yang mengoperasikan POS sama-sama mendapat informasi.
Audit Logs (Catatan Sistem): Upaya pengiriman webhook, terutama yang mengalami kegagalan berulang, akan dicatat dalam log sistem. Administrator dapat memantau riwayat pengiriman ini untuk membantu mendiagnosis masalah jaringan atau endpoint yang tidak valid.

Hal Penting yang Perlu Diketahui

Untuk membangun integrasi yang kokoh menggunakan fitur Webhooks kami, pengembang diwajibkan untuk memperhatikan prinsip-prinsip arsitektur berikut:

Pentingnya Validasi Signature: Jangan pernah mempercayai data yang masuk ke URL Anda secara membabi buta. Selalu validasi header X-Temuya-Signature menggunakan Secret Key webhook Anda. Ini adalah satu-satunya cara untuk memastikan bahwa data tersebut benar-benar berasal dari server Temuya POS dan tidak dimodifikasi oleh peretas di tengah jalan.
Kecepatan Respon adalah Kunci: Endpoint penerima Anda harus memberikan balasan HTTP 200 OK secepat mungkin, idealnya di bawah 3 detik. Jika sistem Anda membutuhkan waktu lama untuk memproses data (misalnya menghasilkan laporan PDF yang berat), terimalah data tersebut, balas server kami dengan 200 OK, dan lakukan proses berat tersebut secara asinkron di antrean sistem Anda sendiri.
Penanganan Duplikasi Data (Idempotency): Meskipun kami berusaha mengirimkan setiap event hanya satu kali, masalah jaringan dapat menyebabkan sebuah webhook dikirim ulang (retry). Pastikan sistem Anda dirancang secara idempotent; artinya, jika sistem Anda menerima webhook dengan ID yang sama lebih dari satu kali, sistem tidak akan menciptakan transaksi ganda atau memperbarui stok dua kali. Gunakan ID unik transaksi sebagai kunci patokan.
Pengamanan URL Endpoint: Sangat disarankan agar URL tujuan webhook Anda menggunakan protokol HTTPS untuk mengenkripsi data selama dalam perjalanan, terutama karena payload webhook sering kali berisi informasi bisnis dan data transaksi pelanggan yang sensitif.
Uji Coba dengan Seksama: Sebelum meluncurkan integrasi ke lingkungan produksi, manfaatkan fitur pengiriman webhook percobaan yang tersedia di panel kontrol developer untuk memastikan bahwa sistem Anda dapat menerima, memvalidasi, dan mengurai payload JSON dengan sempurna.