Panduan Konfigurasi Webhook Lokasi

Webhook lokasi memungkinkan SmartGate mengirim notifikasi otomatis dan real-time ke server HR/payroll milik perusahaan Anda setiap kali ada peristiwa tertentu: penghuni memperbarui foto swafoto, atau penghuni melakukan presensi masuk/keluar gerbang. Server Anda menerima data ini sebagai HTTP POST berformat JSON, tanpa perlu polling data secara berkala ke SmartGate.

Menu ini tersedia di dalam layar Detail Lokasi, diakses lewat halaman Profil:

Langkah 2.1

Buka Profil → Pilih Lokasi

Masuk ke tab Profil, gulir ke bagian Lokasi Saya, lalu ketuk salah satu lokasi tempat Anda menjadi admin untuk masuk ke layar Detail Lokasi.

👤

Screenshot: Profil → Lokasi Saya

web-info/assets/screenshots/webhook-pilih-lokasi.jpeg

1080 x 2400 px

Langkah 2.2

Buka Menu Titik Tiga → Konfigurasi Webhook

Pada layar Detail Lokasi, ketuk ikon titik tiga (⋮) di pojok kanan atas foto sampul lokasi, lalu pilih Konfigurasi Webhook dari daftar menu yang muncul.

💡 Menu ini hanya tampil untuk admin lokasi. Jika tidak muncul, periksa peran keanggotaan Anda pada lokasi tersebut.

⋮

Screenshot: Menu Detail Lokasi

web-info/assets/screenshots/webhook-menu-detail-lokasi.jpeg

1080 x 2400 px

Layar Konfigurasi Webhook terdiri dari beberapa bagian. Isi masing-masing sesuai kebutuhan integrasi dengan sistem HR/payroll Anda:

Langkah 3.1

Status Webhook

Sakelar di bagian paling atas menentukan apakah pengiriman webhook aktif. Saat nonaktif, konfigurasi tetap tersimpan tetapi tidak ada event yang dikirim ke server Anda — berguna untuk menonaktifkan sementara tanpa kehilangan pengaturan.

🔘

Screenshot: Sakelar Status Webhook

web-info/assets/screenshots/webhook-status.jpeg

1080 x 2400 px

Langkah 3.2

URL Webhook (Endpoint)

Masukkan URL lengkap server tujuan, contoh https://api.perusahaan.com/v1/webhook. URL wajib diawali http:// atau https:// — gunakan https:// untuk keamanan data di jalur pengiriman.

🔗

Screenshot: Kolom URL Webhook

web-info/assets/screenshots/webhook-endpoint.jpeg

1080 x 2400 px

Langkah 3.3

Autentikasi Server Pihak Ketiga

Pilih tipe autentikasi (HMAC Signature, Bearer Token, Basic Auth, atau Custom Header) lalu isi Token / Secret Key. Khusus tipe Custom Header, isi juga Nama Header yang diinginkan (mis. X-Api-Key). Detail cara kerja tiap tipe ada di bagian 4.

💡 Saat mengedit konfigurasi yang sudah ada, kosongkan kolom Token / Secret Key jika ingin tetap memakai secret lama — isi hanya jika ingin menggantinya.

🔐

Screenshot: Tipe Autentikasi & Token

web-info/assets/screenshots/webhook-autentikasi.jpeg

1080 x 2400 px

Langkah 3.4

Event yang Di-subscribe

Centang event yang ingin dikirim ke server Anda. Minimal satu event harus dipilih:

• Pembaruan Foto Penghuni — picture.updated
• Presensi Masuk Gerbang — presence.checkin
• Presensi Keluar Gerbang — presence.checkout

☑️

Screenshot: Daftar Event Webhook

web-info/assets/screenshots/webhook-events.jpeg

1080 x 2400 px

Setelah semua kolom terisi, ketuk Simpan Konfigurasi. Jika ini pengisian pertama kali untuk lokasi tersebut, kolom Token / Secret Key wajib diisi.

SmartGate melampirkan header autentikasi pada setiap request webhook berdasarkan tipe yang dipilih. Server tujuan perlu memverifikasi header ini agar hanya menerima request yang sah dari SmartGate:

Jika kolom Token / Secret Key dibiarkan kosong (belum pernah diisi sama sekali), request webhook dikirim tanpa header autentikasi apa pun.

Setelah konfigurasi disimpan, bagian Uji Coba Webhook muncul di bagian bawah layar untuk mengirim payload contoh langsung ke URL webhook tersimpan, tanpa perlu menunggu event sungguhan terjadi.

Langkah 5.1

Pilih Event Pengujian & Kirim

Pilih salah satu event pada dropdown Event Pengujian (ping, presence.checkin, presence.checkout, atau picture.updated), lalu ketuk tombol Uji Coba.

💡 Tombol ini hanya aktif setelah konfigurasi webhook tersimpan (URL endpoint tidak kosong).

📡

Screenshot: Uji Coba & Hasil Pengujian

web-info/assets/screenshots/webhook-uji-coba.jpeg

1080 x 2400 px

Hasil pengujian ditampilkan dalam sebuah kartu berisi:

• Status — "Pengujian Berhasil" (hijau) jika server tujuan membalas HTTP 2xx, atau "Pengujian Gagal" (merah) jika sebaliknya atau koneksi gagal.
• HTTP Status dan Waktu Respons (ms) dari server tujuan.
• Request Payload — isi JSON persis yang dikirim SmartGate.
• Response Body — isi balasan dari server tujuan, atau pesan error jika gagal terhubung.

Semua request webhook dikirim sebagai POST dengan header Content-Type: application/json. Setiap payload selalu memuat field dasar event, timestamp (format ISO-8601 UTC), dan location_id, ditambah field spesifik sesuai jenis event di bawah ini.

6.1 Test Ping — LocationWebhookService.testWebhook

Dipicu manual dari tombol Uji Coba (lihat bagian 5). Semua payload uji coba — apa pun event yang dipilih — selalu memuat flag "is_test": true dan field message, dengan data contoh (dummy). Ini adalah penanda utama untuk membedakan pengiriman uji coba dari data sungguhan pada sistem Anda.

{
  "event": "ping",
  "timestamp": "2026-08-12T09:15:32Z",
  "location_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "is_test": true,
  "message": "Ping test payload from SmartGate Webhook Dispatcher"
}

{
  "event": "picture.updated",
  "timestamp": "2026-08-12T09:15:32Z",
  "location_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "is_test": true,
  "message": "Ping test payload from SmartGate Webhook Dispatcher",
  "user_id": "64a1f2e3d4c5b6a7f8e9d0c1",
  "user_name": "Test Resident",
  "phone": "08123456789",
  "user_code": "USR-99999",
  "photo_url": "https://api.smartgate.id/internal/photos/64a1f2e3d4c5b6a7f8e9d0c1?token=test",
  "approval_token": "apv_test_token",
  "approval_endpoint": "https://api.smartgate.id/v1/webhooks/photo-approval/64a1f2e3d4c5b6a7f8e9d0c1/apv_test_token"
}

{
  "event": "presence.checkin",
  "timestamp": "2026-08-12T09:15:32Z",
  "location_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "is_test": true,
  "message": "Ping test payload from SmartGate Webhook Dispatcher",
  "gate_id": "gate-test",
  "gate_name": "Gerbang Utama Uji Coba",
  "user": {
    "id": "64a1f2e3d4c5b6a7f8e9d0c1",
    "name": "Test Resident",
    "role": "penghuni",
    "unit_no": "Blok A-12"
  },
  "verification_tier": "verified",
  "latitude": -6.2,
  "longitude": 106.816666
}

6.2 Perubahan Foto — PhotoProcessingService.notifyHrForAllLocations

Dikirim otomatis setelah seorang penghuni berhasil mengunggah/memperbarui foto swafoto master, ke setiap lokasi aktif milik penghuni tersebut yang men-subscribe event picture.updated. Tidak seperti payload uji coba, payload sungguhan tidak memuat field is_test maupun message.

{
  "event": "picture.updated",
  "timestamp": "2026-08-12T09:15:32Z",
  "location_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "user_id": "66a9b8c7d6e5f4a3b2c1d0e9",
  "user_name": "Budi Santoso",
  "phone": "081234567890",
  "user_code": "USR-00123",
  "userCode": "USR-00123",
  "photo_url": "https://api.smartgate.id/api/internal/photos/66a9b8c7d6e5f4a3b2c1d0e9?token=9f3c1a7e...b21a",
  "approval_token": "9f3c1a7e...b21a",
  "approval_endpoint": "https://api.smartgate.id/api/v1/webhooks/photo-approval/66a9b8c7d6e5f4a3b2c1d0e9/9f3c1a7e...b21a"
}

userCode (camelCase) adalah duplikat dari user_code yang dipertahankan untuk kompatibilitas sistem lama — nilainya selalu identik.

Alur persetujuan foto (opsional): jika sistem HR Anda perlu menyetujui/menolak foto sebelum dianggap resmi, unduh gambar dari photo_url (URL ini sudah memuat token akses sekali pakai di query ?token=), lalu kirim keputusan ke approval_endpoint yang disertakan pada payload yang sama:

{
  "status": "approved",
  "token": "9f3c1a7e...b21a"
}

status harus "approved" atau "rejected"; token harus sama persis dengan approval_token yang diterima pada payload. Setiap kali foto diperbarui, token baru dibuat dan menggantikan token sebelumnya, sehingga token lama otomatis tidak berlaku lagi.

6.3 Presensi Masuk/Keluar — CheckInOutService.callHrLogPresence

Dikirim secara sinkron tepat setelah presensi masuk/keluar gerbang berhasil dicatat (dan verifikasi wajah cocok), ke lokasi terkait jika event presence.checkin/presence.checkout di-subscribe.

{
  "event": "presence.checkin",
  "timestamp": "2026-08-12T08:02:11Z",
  "location_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "gate_id": "66f2b3c4d5e6f7a8b9c0d1e2",
  "gate_name": "Gerbang Utama",
  "user": {
    "id": "66a9b8c7d6e5f4a3b2c1d0e9",
    "name": "Budi Santoso",
    "role": "penghuni",
    "unit_no": "Blok A-12"
  },
  "verification_tier": "verified",
  "latitude": -6.200123,
  "longitude": 106.816456
}

Kontrak respons yang wajib dipenuhi server Anda: berbeda dari dua event lain, hasil balasan server tujuan untuk event presensi dibaca dan disimpan kembali oleh SmartGate ke dalam riwayat aktivitas penghuni. Balas dengan salah satu bentuk berikut:

{
  "success": true,
  "data": {
    "checkIn": 1755000131000,
    "checkOut": null,
    "presenceDay": "2026-08-12",
    "hrEmployeeId": 4021,
    "attendanceStatus": "ON_TIME"
  }
}

{
  "success": false,
  "message": "Karyawan tidak ditemukan di sistem HR"
}