Webhooks Overview

Webhook digunakan agar server Anda dapat menerima notifikasi secara real-time dari Gerbang Pay saat ada perubahan status pembayaran (misalnya: pelanggan telah mentransfer dana, atau batas waktu tagihan telah habis).

Daripada harus melakukan polling secara berkala ke API GET /v1/payments/{id}, webhook memastikan aplikasi Anda mendapatkan update seketika (push mechanism).

Mengapa Webhook Gerbang Pay Berbeda?

Jika Anda mengintegrasikan Winpay dan Midtrans secara langsung, Anda harus menangani berbagai format webhook dan mekanisme signature yang berbeda-beda.

Dengan Gerbang Pay, kami menyederhanakan proses ini. Sistem kami akan:

1. Menerima callback dari provider (Midtrans/Winpay)
2. Memverifikasi signature masing-masing provider secara internal
3. Menyimpan log callback mentah
4. Mengubah bentuk payload menjadi format Gerbang Pay Universal Webhook
5. Menandatangani ulang payload menggunakan HMAC-SHA256 (webhook_secret milik Anda)
6. Mengirimkannya ke callback_url server Anda

Kapan Webhook Dikirim?

Webhook hanya dikirim untuk perubahan state asinkron. Gerbang Pay TIDAK mengirim webhook untuk event payment.created. Hal ini karena informasi pembuatan tagihan sudah Anda dapatkan secara langsung (synchronous) saat memanggil API POST /v1/payments/create.

Event yang akan memicu webhook:

• payment.paid
• payment.failed
• payment.expired
• payment.cancelled
• payment.challenged
• (Serta event terkait refund jika ada)

Lihat halaman Daftar Event Webhook untuk detail struktur body masing-masing event.

HTTP Headers pada Webhook

Setiap request POST webhook dari Gerbang Pay ke server Anda akan selalu menyertakan header berikut:

Header	Penjelasan
Content-Type	Selalu application/json
X-Gerbang-Event-Id	UUID unik yang melambangkan satu pengiriman event ini (berguna untuk mencegah pemrosesan ganda / idempotency receiver).
X-Gerbang-Event-Type	Jenis event, misalnya payment.paid.
X-Gerbang-Signature	Berisi tanda tangan HMAC-SHA256 payload untuk keperluan validasi keamanan. Format: sha256={hmac_hex}.

Mekanisme Retry (Pengiriman Ulang)

Jika server Anda gagal merespons webhook (mengembalikan HTTP status selain 2xx atau terjadi timeout), Gerbang Pay secara otomatis akan mencoba mengirim ulang webhook tersebut.

• Jumlah Maksimal Retry: 3 kali pengulangan (total 4 kali percobaan)
• Interval: Jeda 10 detik antar percobaan (menggunakan mekanisme RabbitMQ Dead Letter Exchange / DLX)

Jika setelah 3 kali retry server Anda tetap gagal (atau lambat) merespons, pesan tersebut akan dihentikan pemrosesannya dan ditandai gagal permanen di log kami.

💡 Praktik Terbaik: Segera kembalikan status 200 OK sesaat setelah server Anda menerima webhook. Pindahkan proses bisnis yang berat (seperti update ke database, kirim email ke customer) ke background worker di sistem Anda (queue) agar tidak menyebabkan timeout koneksi webhook.

Konfigurasi Webhook URL

1. Login ke Dashboard Gerbang Pay
2. Masuk ke Integration Setup
3. Masukkan endpoint server Anda di kolom Callback / Webhook URL. (Contoh: https://api.toko-anda.com/webhook/gerbang-pay)
4. Copy nilai Webhook Secret yang digenerate oleh sistem. Anda akan menggunakannya untuk memverifikasi signature.