Setup Webhooks

Konfigurasi notifikasi berbasis event untuk aplikasi Anda.

Ringkasan

Webhooks memungkinkan aplikasi Anda menerima notifikasi real-time saat event terjadi di GoValid. Alih-alih melakukan polling API, GoValid mengirim HTTP POST request ke endpoint yang Anda konfigurasi.

Cara Kerja Webhook

1. Anda mendaftarkan URL webhook di GoValid
2. Anda berlangganan event tertentu
3. Saat event terjadi, GoValid mengirim POST request ke URL Anda
4. Aplikasi Anda memproses payload dan merespons dengan 200 OK

Setup Webhook

Via Dashboard

1. Masuk ke my.govalid.org
2. Navigasi ke Akun → Webhooks
3. Klik Add Webhook
4. Masukkan URL endpoint Anda (harus HTTPS)
5. Pilih event untuk berlangganan
6. Atur secret untuk verifikasi signature
7. Klik Save

Opsi developer: setup API

curl -X POST https://api.govalid.org/api/v1/webhooks/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["qr.scanned", "qr.created", "qr.expired"],
    "secret": "your_webhook_secret"
  }'

Event Tersedia

Event	Deskripsi
qr.created	QR code baru dibuat
qr.scanned	QR code di-scan
qr.expired	QR code kedaluwarsa
qr.removed	QR code dihapus/dinonaktifkan
qr.transferred	Kepemilikan QR code ditransfer
subscription.created	Langganan baru dimulai
subscription.cancelled	Langganan dibatalkan
payment.completed	Pembayaran berhasil
payment.failed	Pembayaran gagal
credit.topup	Kredit ditambahkan
counterfeit.detected	Aktivitas pemalsuan potensial terdeteksi

Payload Webhook

{
  "event": "qr.scanned",
  "timestamp": "2025-01-29T12:00:00Z",
  "webhook_id": "wh-001",
  "data": {
    "qr_id": "abc123",
    "qr_title": "Sertifikat Produk #001",
    "scan_location": {
      "country": "ID",
      "city": "Jakarta"
    },
    "device": "mobile",
    "platform": "iOS",
    "is_first_scan": false,
    "scan_count": 15
  },
  "signature": "sha256=a1b2c3d4..."
}

Verifikasi Signature

Setiap webhook menyertakan header X-GoValid-Signature:

X-GoValid-Signature: sha256=a1b2c3d4...

Contoh Python

import hashlib
import hmac

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Contoh Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Praktik Terbaik

1. Respons cepat: Kembalikan 200 OK dalam 5 detik
2. Verifikasi signature: Selalu verifikasi signature webhook
3. Handle duplikat: Gunakan ID event untuk mencegah pemrosesan duplikat
4. Gunakan HTTPS: URL webhook harus menggunakan HTTPS
5. Monitor kegagalan: Periksa status pengiriman webhook di dashboard

Kebijakan Retry

GoValid melakukan retry pengiriman webhook yang gagal:

Percobaan	Delay
1	Segera
2	1 menit
3	5 menit
4	15 menit
5	1 jam

Setelah 5 percobaan gagal, webhook dinonaktifkan.

Pengujian

Uji Endpoint Anda

Gunakan dashboard untuk mengirim event test:

1. Buka Akun → Webhooks
2. Klik Test di sebelah webhook Anda
3. Periksa log server Anda untuk payload test

Development Lokal

Untuk pengujian lokal, gunakan tools seperti:

• ngrok: Expose localhost ke internet
• localtunnel: Alternatif ngrok
• webhook.site: URL webhook sementara untuk testing

Troubleshooting

Webhook Tidak Menerima Event

1. Verifikasi URL dapat diakses dan menggunakan HTTPS
2. Periksa log server untuk request masuk
3. Verifikasi langganan event benar
4. Periksa webhook aktif (tidak dinonaktifkan)

Verifikasi Signature Gagal

1. Pastikan Anda menggunakan secret yang benar
2. Verifikasi Anda melakukan hash pada raw request body
3. Periksa encoding (UTF-8)
4. Bandingkan dengan payload test

Terlalu Banyak Kegagalan

1. Periksa server Anda merespons dalam 5 detik
2. Pastikan endpoint Anda mengembalikan 200 OK
3. Review log error untuk masalah
4. Aktifkan kembali webhook setelah memperbaiki masalah

Terkait

• Referensi API Webhooks - Dokumentasi API lengkap
• Ringkasan Integrasi - Semua opsi integrasi
• Referensi API - Dokumentasi API lengkap