Webhook booking yang idempotent: cara menerima booking.created tanpa proses ganda

Kenapa webhook bisa tiba dua kali?

Termilo menyimpan setiap perubahan booking sebagai satu event, lalu mengirimkannya ke setiap endpoint aktif. Kiriman dihitung berhasil hanya bila endpoint Anda membalas 2xx. Balasan lain, batas waktu habis, atau gangguan jaringan memicu percobaan ulang: sampai enam percobaan, dengan jeda mulai satu menit lalu berlipat. Handler yang sudah memproses event tetapi gagal membalas 2xx menerima event itu lagi.

• Retry otomatis: percobaan berikutnya membawa id, type, dan body yang sama persis; hanya tanda tangan dan timestamp yang baru.
• Kirim ulang manual: admin menekan Kirim ulang dari Riwayat pengiriman di dashboard setelah endpoint Anda pulih.
• Persetujuan otomatis: booking yang langsung terkonfirmasi mengirim booking.created dan booking.confirmed dengan id yang sama; keduanya hanya berbeda pada type.
• Urutan tiba tidak dijamin: retry booking.created dapat tiba setelah booking.confirmed untuk booking yang sama.

Ini bukan kekhususan Termilo. Dokumentasi webhook GitHub menyarankan penerima mengenali kiriman ulang lewat header delivery ID dan membalas 2xx dalam 10 detik (praktik terbaik webhook GitHub). Spesifikasi terbuka Standard Webhooks memakai header webhook-id sebagai kunci idempotensi (spesifikasi Standard Webhooks).

Bagaimana memverifikasi tanda tangan dari body mentah?

Setiap kiriman membawa empat header: X-Termilo-Signature, X-Termilo-Timestamp, X-Termilo-Event-Id, dan X-Termilo-Event-Type. Tanda tangan adalah HMAC-SHA256 atas string timestamp, tanda titik, lalu body mentah, memakai signing secret endpoint Anda. Verifikasi dulu, baru parse JSON.

1. Baca body sebagai byte mentah persis seperti diterima. Jangan parse lalu serialize ulang; urutan kunci atau spasi yang berubah mengubah hasil HMAC.
2. Ambil nilai X-Termilo-Timestamp (UTC epoch detik), lalu bentuk string: timestamp, titik, body mentah.
3. Hitung HMAC-SHA256 atas string itu dengan signing secret endpoint. Tulis hasilnya sebagai sha256= diikuti hex huruf kecil.
4. Bandingkan hasil Anda dengan X-Termilo-Signature memakai perbandingan waktu-konstan: timingSafeEqual di Node.js atau hmac.compare_digest di Python.
5. Tolak kiriman yang tanda tangannya tidak cocok, atau yang timestamp-nya terlalu jauh dari jam server Anda; batas toleransinya Anda tentukan sendiri.

Fungsi verifikasi lengkap untuk Node.js dan Python ada di dokumentasi webhook; salin apa adanya. Signing secret berbeda dengan API key: API key dipakai backend Anda untuk memanggil API v1, signing secret dipakai untuk memeriksa kiriman dari Termilo. Keduanya hanya ditampilkan sekali (autentikasi). Bila signing secret hilang, buat endpoint baru, lalu hapus endpoint lama.

Bagaimana menyimpan id event dan membuat handler idempotent?

Kunci idempotensi Termilo adalah pasangan id dan type. Nilai id di body sama dengan header X-Termilo-Event-Id; nilai type sama dengan X-Termilo-Event-Type. Simpan pasangan itu dengan batasan unik sebelum Anda menjalankan efek samping apa pun. Handler yang benar mengikuti urutan ini:

1. Verifikasi tanda tangan seperti di atas. Bila gagal, balas 401; jangan simpan apa pun.
2. Parse JSON, lalu baca id dan type. Sisipkan pasangan itu ke tabel event yang sudah diproses, dengan batasan unik pada kedua kolom.
3. Bila sisipan ditolak karena pasangan sudah ada, balas 200 tanpa memproses ulang. Inilah jalur untuk retry dan kirim ulang.
4. Bila sisipan berhasil, jalankan efek samping dalam transaksi yang sama, atau taruh pekerjaan berat di antrean Anda sendiri. Bila efek samping gagal, batalkan transaksi termasuk baris id event, lalu balas 500 agar Termilo mengirim lagi.
5. Balas 2xx hanya setelah id event tersimpan permanen. Balasan 2xx sebelum simpan berarti event hilang bila proses Anda mati di tengah jalan.

Dua pengaman tambahan menjaga handler saat event ganda lolos. Pertama, pakai bookingId dari data.booking sebagai kunci upsert, sehingga memproses event yang sama dua kali menghasilkan keadaan akhir yang sama. Kedua, bandingkan occurredAtMs dengan nilai tersimpan sebelum menimpa status, karena urutan tiba tidak dijamin.

Bagaimana memetakan tujuh event ke contact, activity, atau deal?

Semua event memakai amplop yang sama: id, type, occurredAtMs, dan data berisi booking, service, dan customer. Data booking membawa bookingId, status, startsAtMs, endsAtMs, dan timezone; data customer membawa nama dan email. Tabel berikut memetakan tiap event ke tindakan CRM yang aman diulang.

Saring event dari nilai type; endpoint yang dibuat dari dashboard menerima semua event. Balas 2xx untuk type yang tidak Anda pakai. Transisi status lengkap ada di lifecycle booking. Termilo tetap sistem booking; pipeline penjualan tetap milik CRM Anda. Konteks lengkap untuk owner SaaS ada di halaman software booking untuk SaaS.

Bagaimana menguji retry dan kirim ulang dari dashboard?

Uji jalur gagal sebelum produksi. Buka Admin → Webhooks di dashboard Termilo, klik Tambah endpoint, isi URL endpoint (harus HTTPS) dan Deskripsi, lalu klik Simpan endpoint. Salin signing secret dari dialog yang muncul; secret itu tidak ditampilkan lagi.

1. Buat satu booking percobaan dari halaman booking Anda. Buka Riwayat pengiriman: baris booking.created tampil dengan status respons dan jumlah percobaan.
2. Atur handler agar membalas 500 untuk satu kiriman. Riwayat percobaan di detail delivery mencatat percobaan berikutnya dengan jeda berlipat.
3. Kembalikan handler ke normal, lalu klik Kirim ulang pada delivery yang gagal. Handler harus membalas 200 tanpa membuat activity kedua, karena pasangan id dan type sudah tersimpan.
4. Periksa CRM: satu contact, satu activity, status terakhir benar. Activity ganda berarti kunci unik salah, atau 2xx dibalas sebelum simpan.

Setelah enam percobaan gagal, delivery berstatus gagal sampai Anda mengirim ulang manual; riwayat percobaan tetap tersimpan. Agen AI yang terhubung lewat MCP dapat membuat endpoint, mengirim event uji, dan membaca riwayat pengiriman (MCP untuk AI).

Apa yang tidak dikirim webhook: event pembayaran

Webhook Termilo hanya mengirim tujuh event booking. Tidak ada event pembayaran atau deposit. Booking yang meminta deposit lahir sebagai booking.created dengan status held; perubahan berikutnya tiba sebagai booking.confirmed atau booking.expired. Nominal dan status pembayaran dibaca dari akun gateway pembayaran milik bisnis.

• Webhook masuk dari CRM ke Termilo tidak tersedia; perubahan dari sisi CRM dilakukan lewat API v1 (referensi API).
• Body event memuat nama dan email pelanggan, bukan nomor telepon; ambil detail pelanggan lewat API v1.
• Retry dan kirim ulang memakai body kiriman pertama, bukan data terbaru. Untuk keadaan terkini, baca booking lewat API v1.

Klinik, salon, dan bengkel memakai pola yang sama untuk kasir atau CRM; lihat hub software booking.