وثائق واجهة برمجة التطبيقات
ويب هوكس

ويب هوكس

استقبل إشعارات في الوقت الفعلي عند حدوث أحداث في مؤسستك. تتيح لك Webhooks بناء تكاملات تفاعلية تستجيب على الفور لمسح رموز QR وغيرها من الأحداث.

في الوقت الحقيقي

احصل على إشعارات فورية عند حدوث الأحداث، دون الحاجة إلى الاستطلاع

آمن

تتحقق توقيعات HMAC من أن الويب هوكس تأتي من iloveQR

موثوق

إعادة المحاولات التلقائية مع زيادة زمن الانتظار بشكل أسي للتسليمات الفاشلة

إعداد الويب هوكس

قم بتكوين الويب هوكس من خلال لوحة التحكم أو واجهة برمجة التطبيقات لبدء تلقي الأحداث.

1

إنشاء نقطة نهاية webhook

قم بإعداد نقطة نهاية HTTPS على خادمك لاستقبال حمولات الويب هوك.

2

سجل الويب هوك

أضف عنوان URL لنقطة النهاية الخاصة بك واختر الأحداث التي ترغب في الاشتراك فيها.

3

تحقق من التوقيعات

قم بتنفيذ التحقق من التوقيع لضمان أن الحمولة أصلية.

تسجيل 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"
  }'

أحداث Webhook

اشترك في الأحداث التي تحتاجها. كل نوع من الأحداث له هيكل حمولة محدد.

أحداث رمز الاستجابة السريعة

qr.createdتم إنشاء رمز QR جديد
qr.updatedتم تحديث رمز الاستجابة السريعة
qr.deletedتم حذف رمز الاستجابة السريعة
qr.scannedتم مسح رمز الاستجابة السريعة
qr.archivedتم أرشفة رمز QR
qr.restoredتم استعادة رمز QR من الأرشيف

أحداث الاشتراك

subscription.createdتم إنشاء اشتراك جديد
subscription.updatedتم تحديث الاشتراك
subscription.cancelledتم إلغاء الاشتراك
subscription.payment_succeededتمت عملية الدفع بنجاح
subscription.payment_failedفشل الدفع

فعاليات الفريق

member.joinedانضم عضو إلى المنظمة
member.leftغادر أحد الأعضاء المنظمة
member.role_changedتم تغيير دور العضو

حمولة الويب هوك

تتبع جميع حمولات الويب هوك هيكلًا متسقًا مع بيانات الحدث وبيانات.

مثال: 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
    }
  }
}
مثال: 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"
    }
  }
}

التحقق من Webhooks

تأكد دائمًا من التحقق من توقيعات الويب هوك لضمان أن الحمولة جاءت من iloveQR ولم يتم العبث بها أثناء النقل.

ترويسة التوقيع

يتضمن كل طلب ويب هوك رأس X-Webhook-Signature يحتوي على توقيع HMAC-SHA256 لجسم الطلب.

مثال تحقق 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');
});
مثال التحقق باستخدام بايثون
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 محاولات فاشلة، يتم وضع علامة على الويب هوك على أنه فاشل ونتوقف عن المحاولة مرة أخرى. ستتلقى إشعارًا عبر البريد الإلكتروني حول الفشل.

الخطوات التالية

هل أنت مستعد للبدء؟ استكشف المزيد من الموارد: