Webhook - Dokumentasi API - iloveQR

Dokumentasi API

Webhook

Terima notifikasi waktu nyata saat peristiwa terjadi di organisasi Anda. Webhook memungkinkan Anda membangun integrasi reaktif yang merespons segera terhadap pemindaian kode QR dan peristiwa lainnya.

Waktu nyata

Dapatkan pemberitahuan instan saat peristiwa terjadi, tanpa perlu polling

Aman

Tanda tangan HMAC memverifikasi bahwa webhook berasal dari iloveQR

Handal

Pengulangan otomatis dengan backoff eksponensial untuk pengiriman yang gagal

Mengatur Webhook

Konfigurasi webhook melalui dasbor atau API untuk mulai menerima peristiwa.

Buat endpoint webhook

Atur endpoint HTTPS di server Anda untuk menerima payload webhook.

Daftarkan webhook

Tambahkan URL endpoint Anda dan pilih peristiwa mana yang akan disubscribe.

Verifikasi tanda tangan

Terapkan verifikasi tanda tangan untuk memastikan payload otentik.

Daftarkan Webhook

curl -X POST \
  "https://api.iloveqr.com/api/v1/organizations/org_abc123/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/iloveqr",
    "events": ["qr.scanned", "qr.created", "qr.updated"],
    "secret": "your_webhook_secret"
  }'

Peristiwa Webhook

Berlangganan ke peristiwa yang Anda butuhkan. Setiap jenis peristiwa memiliki struktur payload tertentu.

Peristiwa Kode QR

qr.createdKode QR baru telah dibuat

qr.updatedKode QR telah diperbarui

qr.deletedKode QR telah dihapus

qr.scannedKode QR telah dipindai

qr.archivedKode QR telah diarsipkan

qr.restoredKode QR telah dipulihkan dari arsip

Peristiwa Langganan

subscription.createdLangganan baru telah dibuat

subscription.updatedLangganan telah diperbarui

subscription.cancelledLangganan telah dibatalkan

subscription.payment_succeededPembayaran berhasil

subscription.payment_failedPembayaran gagal

Peristiwa Tim

member.joinedSeorang anggota bergabung dengan organisasi

member.leftSeorang anggota meninggalkan organisasi

member.role_changedPeran seorang anggota telah diubah

Payload Webhook

Semua payload webhook mengikuti struktur yang konsisten dengan metadata acara dan data.

Contoh: acara qr.scanned

{
  "id": "evt_1a2b3c4d5e6f",
  "event": "qr.scanned",
  "createdAt": "2024-01-15T14:30:00Z",
  "organizationId": "org_abc123",
  "data": {
    "qrCodeId": "qr_xyz789",
    "qrCodeName": "Product Landing Page",
    "shortCode": "xyz789",
    "destinationUrl": "https://example.com/product",
    "scan": {
      "id": "scan_123abc",
      "timestamp": "2024-01-15T14:30:00Z",
      "location": {
        "country": "US",
        "city": "New York",
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "isUnique": true
    }
  }
}

Contoh: acara qr.created

{
  "id": "evt_7g8h9i0j1k2l",
  "event": "qr.created",
  "createdAt": "2024-01-15T10:00:00Z",
  "organizationId": "org_abc123",
  "data": {
    "qrCode": {
      "id": "qr_newcode",
      "type": "URL",
      "name": "New Campaign QR",
      "shortUrl": "https://ilqr.co/newcode",
      "destinationUrl": "https://example.com/campaign",
      "createdBy": "user_abc123"
    }
  }
}

Memverifikasi Webhook

Selalu verifikasi tanda tangan webhook untuk memastikan payload berasal dari iloveQR dan tidak diubah selama pengiriman.

Header Tanda Tangan

Setiap permintaan webhook menyertakan header X-Webhook-Signature yang berisi tanda tangan HMAC-SHA256 dari body permintaan.

Contoh Verifikasi Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/iloveqr', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  const event = req.body;
  console.log('Received event:', event.event);

  res.status(200).send('OK');
});

Contoh Verifikasi Python

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your Flask handler
@app.route('/webhooks/iloveqr', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data()

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.get_json()
    print(f"Received event: {event['event']}")

    return 'OK', 200

Praktik Terbaik

Tanggapi dengan cepat

Kembalikan respons 2xx dalam waktu 5 detik. Proses webhook secara asinkron jika penanganan Anda memerlukan waktu lebih lama.

Tangani duplikat

Simpan ID acara dan periksa untuk duplikat. Webhook mungkin dikirim lebih dari sekali dalam kasus yang jarang terjadi.

Gunakan HTTPS

Selalu gunakan endpoint HTTPS. Kami tidak mengirimkan webhook ke URL HTTP.

Pantau kegagalan

Siapkan pemantauan untuk kegagalan pengiriman webhook. Periksa log webhook di dasbor untuk debugging.

Kebijakan Pengulangan

Jika endpoint Anda mengembalikan kesalahan atau tidak merespons, kami secara otomatis mencoba ulang pengiriman dengan backoff eksponensial:

Percobaan	Penundaan
pengulangan ke-1	1 menit
pengulangan ke-2	5 menit
pengulangan ke-3	30 menit
pengulangan ke-4	2 jam
pengulangan ke-5 (akhir)	24 jam

Catatan: Setelah 5 percobaan gagal, webhook ditandai sebagai gagal dan kami berhenti mencoba ulang. Anda akan menerima pemberitahuan email tentang kegagalan tersebut.

Langkah Selanjutnya

Siap untuk memulai? Jelajahi lebih banyak sumber daya: