Menyiapkan Pengiriman Outbound Webhook

Penyiapan Cepat

Sebagian besar hotel menyelesaikan penyiapan ini dalam 5 hingga 10 menit.

Panduan ini membantu Anda mengirim event JSON guest_verified setelah verifikasi tamu dan sinkronisasi PMS.

Buka: Settings → Outbound Webhook

Header tanda tangan

Setiap pengiriman menyertakan X-Vouch-Signature. Penerima Anda harus memvalidasi header tersebut sebelum mempercayai payload.

Nilai sensitif

Siapa pun yang memiliki akses ke halaman ini dapat melihat nilai header yang tersimpan dan secret penandatanganan HMAC. Log pengiriman menampilkan payload request lengkap dan detail respons. Catatan perubahan audit tetap menyamarkan nilai-nilai tersebut. Lindungi akses ke Settings → Outbound Webhook dan hindari membagikan screenshot.

Referensi Cepat

Pengaturan	Yang Dikontrol	Yang Anda Lihat
Enabled	Mengaktifkan atau menonaktifkan pengiriman outbound webhook	Toggle tetap aktif setelah Anda menyimpan
Webhook URL	URL tujuan pengiriman	AVA menerima URL penerima Anda
Headers	Header autentikasi statis untuk penerima Anda	Nilai yang tersimpan tetap terlihat setelah disimpan
Payload Fields	Field tamu yang dikirim	Hanya field yang dicentang yang muncul dalam pengiriman
Marketing consent	Penyertaan marketingConsent tingkat atas	Kartu status menampilkan Included atau Omitted
Max attempts	Jumlah percobaan ulang untuk pengiriman yang gagal	Nilainya tetap antara 1 dan 10
HMAC signing secret	Penandatanganan payload untuk setiap pengiriman	Nilai yang tersimpan tetap terlihat; wajib diisi saat diaktifkan atau diuji
Send Test	Mengirim satu pengiriman uji	Uji terbaru muncul di Delivery Logs
Delivery Logs	Status dan payload pengiriman terbaru	Anda melihat 10 record per halaman, beserta status, percobaan, HTTP status, response body, detail payload, dan navigasi halaman

Sebelum Memulai

Pastikan hal-hal dasar berikut:

• Anda memiliki izin settings:write
• Anda mengetahui URL penerima
• Anda mengetahui header autentikasi statis yang diperlukan
• Anda memiliki secret penandatanganan HMAC
• Anda mengetahui field tamu yang dibutuhkan penerima

Nilai secret yang tersimpan

Nilai header yang tersimpan dan secret penandatanganan HMAC tetap terlihat setelah Anda menyimpannya. Masukkan nilai baru jika Anda perlu mengganti secret.

Kapan Dikirim

AVA mengirim webhook setelah verifikasi tamu berhasil. Nama event-nya adalah guest_verified. AVA tidak mengirim webhook jika sinkronisasi PMS gagal.

Request menggunakan JSON POST. AVA menyertakan header statis Anda pada setiap pengiriman.

Konfigurasikan Webhook

Aktifkan

1. Buka Settings → Outbound Webhook.

2. Aktifkan Enabled.

3. Masukkan Webhook URL.

4. Klik Save.

   ✓ AVA menyimpan endpoint untuk pengiriman berikutnya.

Tambahkan Header Kustom

Gunakan header saat penerima Anda mengharapkan autentikasi statis. AVA mengirimkannya pada setiap JSON POST. Sebagai contoh, Anda dapat mengirim Authorization: token api_key:api_secret.

1. Klik Add.

2. Masukkan nama header.

3. Masukkan nilai header.

4. Aktifkan Secret untuk nilai sensitif.

5. Klik Save.

   ✓ Nilai header yang tersimpan tetap terlihat setelah disimpan.

Pilih Field Payload

Pilih field yang dibutuhkan penerima Anda dari kartu Payload Fields. Katalog tersebut mencakup field reservasi dan semua field dari Settings → Check-In → Registration Form. Marketing consent tidak termasuk dalam checklist ini.

1. Centang setiap field yang ingin Anda kirim.

2. Hapus centang field yang tidak dibutuhkan penerima.

3. Klik Save.

   ✓ Hanya field yang dicentang yang muncul dalam pengiriman berikutnya.

Field Payload yang Tersedia

Grup	Field di AVA	Properti JSON
Reservation	Confirmation number	reservation.confirmationNumber
Reservation	Arrival date	reservation.arrivalDate
Reservation	Departure date	reservation.departureDate
Guest	First name	guest.firstName
Guest	Last name	guest.lastName
Guest	Email	guest.email
Guest	Phone	guest.phone
Guest	Nationality	guest.nationality
Guest	Document number	guest.documentNumber
Guest	Date of birth	guest.birthDate
Guest	Postal code	guest.postalCode
Guest	Country of residence	guest.countryCode
Guest	Address	guest.addressLine
Guest	City	guest.cityName
Guest	State or province	guest.stateProv
Guest	Purpose of stay	guest.purposeOfStay
Guest	Estimated arrival time	guest.preCheckInTime
Guest	Gender	guest.gender
Guest	Occupation	guest.occupation
Guest	Place of departure	guest.placeOfDeparture
Guest	Next destination	guest.nextDestination
Guest	Departure time	guest.departureTime

Jika field yang dipilih kosong, AVA mungkin tidak menyertakan properti tersebut dalam JSON. Purpose of stay dan Estimated arrival time dapat menggunakan nilai check-in yang tersimpan. AVA menggabungkan bagian alamat untuk Place of departure dan Next destination. Jika tamu memilih alamat saat ini, AVA menggunakan alamat tersebut sebagai tujuan.

Periksa Status Marketing Consent

Kartu Marketing consent menampilkan empat nilai:

• Guest prompt — apakah tamu melihat opsi ikut serta dalam marketing
• Collection setting — model persetujuan yang digunakan PMS Anda
• Registration field — apakah Marketing consent terlihat
• Webhook payload — apakah AVA menyertakan marketingConsent

Checklist Payload Fields tidak mengubah nilai-nilai ini.

1. Buka Settings → Check-In → Card & Consent.

2. Untuk persetujuan terperinci, aktifkan Promotional Mailing List.

3. Untuk persetujuan umum, aktifkan Show marketing email opt-in during signature.

4. Buka Settings → Check-In → Registration Form.

5. Atur Show to menjadi All guests untuk Marketing consent.

6. Simpan kedua halaman pengaturan.

   ✓ Kartu status menampilkan Included jika kedua prasyarat sudah siap. ✓ AVA mengirim true atau false, berdasarkan pilihan tamu.

AVA tidak menyertakan marketingConsent jika opt-in dinonaktifkan atau field disembunyikan. Persetujuan kontak melalui telepon dan email tidak dengan sendirinya mengaktifkan marketing consent.

Atur Percobaan Ulang dan Signing Secret

Gunakan percobaan ulang untuk kegagalan pengiriman sementara. Atur signing secret agar penerima Anda dapat memverifikasi setiap payload.

1. Masukkan nilai pada Max attempts.

2. Gunakan nilai dari 1 hingga 10.

3. Masukkan HMAC signing secret Anda.

4. Klik Save.

   ✓ AVA mencoba lagi untuk kegagalan 429, 5xx, dan timeout. ✓ Error validasi dan autentikasi tetap tercatat tanpa percobaan ulang.

Ganti Secret yang Tersimpan

Gunakan langkah ini saat header secret atau signing secret sudah ada. Nilai yang tersimpan saat ini muncul langsung di field-nya.

1. Pilih nilai saat ini di field header atau HMAC.

2. Masukkan nilai baru.

3. Klik Save.

   ✓ Nilai baru muncul setelah disimpan dan berlaku untuk pengiriman berikutnya.

Kirim Pengiriman Uji

Gunakan pengiriman uji setelah Anda menyimpan pengaturan. Uji tersebut menggunakan konfigurasi tersimpan terbaru. Uji tersebut juga menggunakan secret penandatanganan HMAC yang tersimpan.

1. Klik Send Test.

2. Tunggu pesan sukses.

3. Buka Delivery Logs untuk memastikan baris baru muncul.

   ✓ Baris terbaru menampilkan test delivery.

Simpan terlebih dahulu

Jika Anda mengubah sesuatu di halaman, simpan sebelum mengirim uji. AVA menonaktifkan tombol uji sampai perubahan yang belum disimpan diselesaikan.

Tinjau Delivery Logs

Delivery logs membantu Anda memeriksa percobaan terbaru. Setiap halaman menampilkan 10 baris. Setiap baris menampilkan status pengiriman, stempel waktu, percobaan, HTTP status, dan detail. Anda juga dapat membuka payload request lengkap dan response body. Gunakan kontrol halaman untuk berpindah antara pengiriman yang lebih lama dan yang lebih baru.

Status	Artinya
delivered	Penerima menerima pengiriman
processing	AVA masih menangani pengiriman
retrying	AVA akan mencoba lagi nanti
pending	AVA telah mengantrekan pengiriman
failed	AVA berhenti mencoba lagi mengirimkan pengiriman

1. Klik Refresh delivery logs untuk memuat ulang halaman saat ini.

2. Gunakan First page, Previous, Next, atau Last page jika ada lebih banyak hasil.

3. Buka satu baris untuk meninjau detail respons.

4. Perluas View request payload jika Anda perlu melihat JSON yang dikirim.

5. Perluas View response untuk memeriksa response body persis dari penerima.

   ✓ Penghitung halaman menampilkan Page X of Y saat ada beberapa halaman. ✓ Kontrol tetap tersedia sampai Anda mencapai halaman pertama atau terakhir.

Detail log sensitif

Delivery logs menampilkan payload request persis dan response body yang dikembalikan oleh penerima Anda. Payload dapat berisi data tamu, jadi perluas detail hanya saat melakukan troubleshooting.

Pemecahan Masalah

Halaman Tidak Dapat Dimuat

Yang Anda lihat: Anda melihat Unable to load outbound webhook settings.

Perbaikan:

1. Klik Retry.
2. Refresh halaman.
3. Pastikan Anda berada di properti yang benar.
4. Coba lagi setelah masuk kembali jika diperlukan.

Penyimpanan Gagal Saat Anda Mengaktifkan Webhook

Yang Anda lihat: Penyimpanan gagal setelah Anda mengaktifkan Enabled.

Perbaikan:

1. Masukkan HMAC signing secret.
2. Simpan lagi.
3. Jika Anda sudah memilikinya, ganti secret tersebut, bukan mengosongkannya.

Send Test Tetap Dinonaktifkan

Yang Anda lihat: Send Test dinonaktifkan setelah Anda mengedit halaman.

Perbaikan:

1. Klik Save terlebih dahulu.
2. Tunggu pesan sukses.
3. Coba Send Test lagi.
4. Pastikan Anda memiliki izin pengaturan.

Webhook URL Ditolak

Yang Anda lihat: Penyimpanan atau uji gagal untuk beberapa URL tujuan.

Perbaikan:

1. Gunakan URL HTTPS publik.
2. Hapus alamat private, reserved, loopback, dan site-local.
3. Coba lagi dengan penerima publik.

Delivery Logs Tetap Kosong

Yang Anda lihat: Delivery Logs belum menampilkan baris apa pun.

Perbaikan:

1. Klik Send Test.
2. Tunggu event verifikasi tamu.
3. Klik Refresh delivery logs.
4. Periksa penghitung halaman dan kontrol halaman jika Anda mengharapkan pengiriman yang lebih lama.
5. Periksa lagi setelah check-in berikutnya yang memenuhi syarat.
6. Gunakan Last page jika Anda perlu berpindah cepat ke pengiriman yang lebih lama.

Field Registrasi Baru Tidak Muncul

Yang Anda lihat: Field registrasi tidak muncul dalam Payload Fields.

Perbaikan:

1. Refresh Settings → Outbound Webhook.
2. Pastikan halaman dimuat tanpa error.
3. Periksa field tersebut pada tabel Payload Fields Available di atas.
4. Buka Settings → Check-In → Registration Form.
5. Atur Show to menjadi All guests jika tamu harus memberikan nilainya.
6. Simpan formulir registrasi dan muat ulang halaman webhook.

Visibilitas mengontrol pengumpulan data tamu. Visibilitas tidak mengontrol apakah field tersebut muncul dalam katalog webhook.

Marketing Consent Tidak Ada dalam Payload

Yang Anda lihat: Webhook tidak menyertakan marketingConsent.

Perbaikan:

1. Buka Settings → Check-In → Card & Consent.
2. Aktifkan opt-in marketing yang sesuai untuk tamu.
3. Buka Settings → Check-In → Registration Form.
4. Atur Show to menjadi All guests untuk Marketing consent.
5. Simpan kedua halaman pengaturan.
6. Pastikan kartu status menampilkan Included.
7. Selesaikan verifikasi tamu baru.

AVA tidak menyertakan properti ini jika tamu tidak dapat melihat opt-in atau field tersebut. Hubungi support jika pengaturan terlihat tetapi properti tetap tidak ada.

Masih Terkendala?

Hubungi success@vouch-technologies.com jika:

• ❌ Halaman masih tidak dapat dimuat setelah dicoba lagi
• ❌ Penyimpanan gagal setelah Anda menambahkan secret penandatanganan HMAC
• ❌ Pengiriman uji tidak muncul dalam log

Sertakan:

• URL penerima yang Anda gunakan
• Nama header apa pun yang Anda tambahkan
• Screenshot kartu Delivery Logs dengan secret dan data tamu yang disamarkan

Panduan Terkait

• Field Registrasi
• Disclaimer Kartu Registrasi
• Menyiapkan Push Notifications