ويب هوكس
استقبل إشعارات في الوقت الفعلي عند حدوث أحداث في مؤسستك. تتيح لك Webhooks بناء تكاملات تفاعلية تستجيب على الفور لمسح رموز QR وغيرها من الأحداث.
في الوقت الحقيقي
احصل على إشعارات فورية عند حدوث الأحداث، دون الحاجة إلى الاستطلاع
آمن
تتحقق توقيعات HMAC من أن الويب هوكس تأتي من iloveQR
موثوق
إعادة المحاولات التلقائية مع زيادة زمن الانتظار بشكل أسي للتسليمات الفاشلة
إعداد الويب هوكس
قم بتكوين الويب هوكس من خلال لوحة التحكم أو واجهة برمجة التطبيقات لبدء تلقي الأحداث.
إنشاء نقطة نهاية webhook
قم بإعداد نقطة نهاية HTTPS على خادمك لاستقبال حمولات الويب هوك.
سجل الويب هوك
أضف عنوان URL لنقطة النهاية الخاصة بك واختر الأحداث التي ترغب في الاشتراك فيها.
تحقق من التوقيعات
قم بتنفيذ التحقق من التوقيع لضمان أن الحمولة أصلية.
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
اشترك في الأحداث التي تحتاجها. كل نوع من الأحداث له هيكل حمولة محدد.
أحداث رمز الاستجابة السريعة
qr.createdتم إنشاء رمز QR جديدqr.updatedتم تحديث رمز الاستجابة السريعةqr.deletedتم حذف رمز الاستجابة السريعةqr.scannedتم مسح رمز الاستجابة السريعةqr.archivedتم أرشفة رمز QRqr.restoredتم استعادة رمز QR من الأرشيفأحداث الاشتراك
subscription.createdتم إنشاء اشتراك جديدsubscription.updatedتم تحديث الاشتراكsubscription.cancelledتم إلغاء الاشتراكsubscription.payment_succeededتمت عملية الدفع بنجاحsubscription.payment_failedفشل الدفعفعاليات الفريق
member.joinedانضم عضو إلى المنظمةmember.leftغادر أحد الأعضاء المنظمةmember.role_changedتم تغيير دور العضوحمولة الويب هوك
تتبع جميع حمولات الويب هوك هيكلًا متسقًا مع بيانات الحدث وبيانات.
{
"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"
}
}
}التحقق من Webhooks
تأكد دائمًا من التحقق من توقيعات الويب هوك لضمان أن الحمولة جاءت من iloveQR ولم يتم العبث بها أثناء النقل.
ترويسة التوقيع
يتضمن كل طلب ويب هوك رأس X-Webhook-Signature يحتوي على توقيع HMAC-SHA256 لجسم الطلب.
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', 200أفضل الممارسات
استجب بسرعة
أعد استجابة 2xx في غضون 5 ثوانٍ. قم بمعالجة الويب هوكس بشكل غير متزامن إذا استغرق التعامل وقتًا أطول.
تعامل مع التكرارات
قم بتخزين معرف الحدث وتحقق من التكرارات. قد يتم تسليم الويب هوكس أكثر من مرة في حالات نادرة.
استخدم HTTPS
استخدم دائمًا نقاط نهاية HTTPS. نحن لا نقدم webhooks إلى عناوين URL HTTP.
مراقبة الفشل
قم بإعداد المراقبة لفشل تسليم الويب هوك. تحقق من سجلات الويب هوك في لوحة التحكم لأغراض تصحيح الأخطاء.
سياسة إعادة المحاولة
إذا كانت نقطة النهاية الخاصة بك ترجع خطأ أو لا تستجيب، فإننا نقوم تلقائيًا بإعادة محاولة التسليم مع زيادة زمنية متزايدة:
| محاولة | تأخير |
|---|---|
| إعادة المحاولة الأولى | 1 دقيقة |
| إعادة المحاولة الثانية | 5 دقائق |
| محاولة ثالثة | 30 دقيقة |
| المحاولة الرابعة | ساعتان |
| المحاولة الخامسة (الأخيرة) | 24 ساعة |
ملاحظة: بعد 5 محاولات فاشلة، يتم وضع علامة على الويب هوك على أنه فاشل ونتوقف عن المحاولة مرة أخرى. ستتلقى إشعارًا عبر البريد الإلكتروني حول الفشل.
الخطوات التالية
هل أنت مستعد للبدء؟ استكشف المزيد من الموارد: