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.
Webhook uç noktası oluşturun
Sunucunuzda webhook yüklerini almak için bir HTTPS uç noktası ayarlayın.
Webhook'u kaydet.
Sonuç URL'nizi ekleyin ve hangi etkinliklere abone olacağınızı seçin.
İmzaları doğrula
Yüklerin gerçek olduğunu doğrulamak için imza doğrulama uygulayın.
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şturulduqr.updatedBir QR kodu güncellendiqr.deletedBir QR kodu silindiqr.scannedBir QR kodu tarandıqr.archivedBir QR kodu arşivlendiqr.restoredBir QR kodu arşivden geri yüklendi.Abonelik Etkinlikleri
subscription.createdYeni bir abonelik oluşturuldusubscription.updatedBir abonelik güncellendisubscription.cancelledBir abonelik iptal edildisubscription.payment_succeededBir ödeme başarılı oldusubscription.payment_failedBir ödeme başarısız olduTakı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.
{
"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
}
}
}{
"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.
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');
});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', 200En İ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şim | Gecikme |
|---|---|
| 1. deneme | 1 dakika |
| 2. deneme | 5 dakika |
| 3. deneme | 30 dakika |
| 4. deneme | 2 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: