API Dokümantasyonu
Webhooks

Webhooks

Kuruluşunuzda olaylar gerçekleştiğinde gerçek zamanlı bildirimler alın. Webhook'lar, QR kodu taramaları ve diğer olaylara hemen yanıt veren reaktif entegrasyonlar oluşturmanıza olanak tanır.

Gerçek zamanlı

Olaylar gerçekleştiğinde anında bildirim alın, anket yapmaya gerek yok.

Güvenli

HMAC imzaları, webhook'ların iloveQR'dan geldiğini doğrular.

Güvenilir

Başarısız teslimatlar için üstel geri çekilme ile otomatik yeniden denemeler

Webhook'ları Ayarlama

Webhook'ları almak için panodan veya API'den yapılandırın.

1

Webhook uç noktası oluşturun

Sunucunuzda webhook yüklerini almak için bir HTTPS uç noktası ayarlayın.

2

Webhook'u kaydet.

Sonuç URL'nizi ekleyin ve hangi etkinliklere abone olacağınızı seçin.

3

İmzaları doğrula

Yüklerin gerçek olduğunu doğrulamak için imza doğrulama uygulayın.

Webhook Kaydı
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"
  }'

Webhook Olayları

Gerekli etkinliklere abone olun. Her etkinlik türünün belirli bir yük yapısı vardır.

QR Kod Etkinlikleri

qr.createdYeni bir QR kodu oluşturuldu
qr.updatedBir QR kodu güncellendi
qr.deletedBir QR kodu silindi
qr.scannedBir QR kodu tarandı
qr.archivedBir QR kodu arşivlendi
qr.restoredBir QR kodu arşivden geri yüklendi.

Abonelik Etkinlikleri

subscription.createdYeni bir abonelik oluşturuldu
subscription.updatedBir abonelik güncellendi
subscription.cancelledBir abonelik iptal edildi
subscription.payment_succeededBir ödeme başarılı oldu
subscription.payment_failedBir ödeme başarısız oldu

Takım Etkinlikleri

member.joinedBir üye organizasyona katıldı.
member.leftBir üye organizasyondan ayrıldı.
member.role_changedBir üyenin rolü değiştirildi.

Webhook Yükü

Tüm webhook yükleri, olay meta verileri ve verilerle tutarlı bir yapıyı takip eder.

Örnek: qr.scanned Olay
{
  "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
    }
  }
}
Örnek: qr.created Etkinliği
{
  "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"
    }
  }
}

Webhook'ları Doğrulama

Webhook imzalarını her zaman doğrulayın, böylece yükün iloveQR'den geldiğinden ve iletim sırasında değiştirilmediğinden emin olun.

İmza Başlığı

Her webhook isteği, istek gövdesinin HMAC-SHA256 imzasını içeren bir X-Webhook-Signature başlığı içerir.

Node.js Doğrulama Örneği
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');
});
Python Doğrulama Örneği
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

En İyi Uygulamalar

Hızlı yanıt verin

5 saniye içinde 2xx yanıtı döndürün. İşlemeniz daha uzun sürerse web kancalarını asenkron olarak işleyin.

Çiftleri yönet

Etkinlik kimliğini saklayın ve tekrarları kontrol edin. Webhook'lar nadir durumlarda birden fazla kez teslim edilebilir.

HTTPS kullanın

Her zaman HTTPS uç noktaları kullanın. HTTP URL'lerine webhook göndermiyoruz.

Gözetim arızaları

Webhook teslimat hataları için izleme ayarlayın. Hata ayıklama için kontrol panelindeki webhook günlüklerini kontrol edin.

Tekrar Deneme Politikası

Eğer uç noktanız bir hata dönerse veya yanıt vermezse, teslimatı otomatik olarak üssel geri çekilme ile yeniden deneriz:

GirişimGecikme
1. deneme1 dakika
2. deneme5 dakika
3. deneme30 dakika
4. deneme2 saat
5. deneme (son)24 saat

Not: 5 başarısız denemeden sonra, webhook başarısız olarak işaretlenir ve tekrar denemeyi durdururuz. Başarısızlık hakkında bir e-posta bildirimi alacaksınız.

Sonraki Adımlar

Başlamaya hazır mısınız? Daha fazla kaynağı keşfedin: