Webhooks

Integrasi berbasis event untuk notifikasi real-time.

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.

URL Dasar

https://api.govalid.org/api/v1/webhooks/

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
institution.staff.invited	Anggota staf diundang

Daftarkan Webhook

POST /api/v1/webhooks/

Body Request

{
  "url": "https://your-server.com/webhook",
  "events": ["qr.scanned", "qr.created", "qr.expired"],
  "secret": "your_webhook_secret"
}

Field

Field	Tipe	Wajib	Deskripsi
url	string	Ya	URL endpoint webhook Anda (harus HTTPS)
events	array	Ya	Daftar event untuk berlangganan
secret	string	Ya	Secret untuk verifikasi signature
description	string	Tidak	Deskripsi untuk referensi Anda
active	boolean	Tidak	Aktifkan/nonaktifkan webhook (default: true)

Respons

{
  "id": "wh-001",
  "url": "https://your-server.com/webhook",
  "events": ["qr.scanned", "qr.created", "qr.expired"],
  "active": true,
  "created_at": "2025-01-29T12:00:00Z"
}

Daftar Webhook

GET /api/v1/webhooks/

Respons

{
  "count": 2,
  "results": [
    {
      "id": "wh-001",
      "url": "https://your-server.com/webhook",
      "events": ["qr.scanned", "qr.created"],
      "active": true,
      "last_triggered": "2025-01-29T15:00:00Z",
      "success_count": 150,
      "failure_count": 2,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Update Webhook

PATCH /api/v1/webhooks/{id}/

Hapus Webhook

DELETE /api/v1/webhooks/{id}/

Payload Webhook

Saat event terjadi, GoValid mengirim POST request ke endpoint Anda:

{
  "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": "US",
      "city": "New York",
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "device": "mobile",
    "platform": "iOS",
    "is_first_scan": false,
    "scan_count": 15
  },
  "signature": "sha256=a1b2c3d4..."
}

Verifikasi Signature Webhook

Setiap payload webhook menyertakan header signature untuk verifikasi:

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

Verifikasi 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)

Verifikasi 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;
}

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.

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

Pengujian Webhook

Endpoint Test

POST /api/v1/webhooks/{id}/test/

Mengirim event test untuk memverifikasi endpoint Anda berfungsi.

Log Webhook

GET /api/v1/webhooks/{id}/logs/

Lihat riwayat pengiriman untuk webhook.

Terkait

• Ringkasan Integrasi - Semua opsi integrasi
• Referensi API - Dokumentasi API lengkap
• Contoh Kode - Kasus penggunaan umum