ما الخطط التي تدعم الويب هوكس؟

الويب هوكس متاحة في خطط Pro وBusiness وEnterprise. في الخطة المجانية الويب هوكس غير متاحة -- استخدم التصدير اليدوي أو واجهة برمجة التطبيقات العامة.

كم مرة يعيد tikento الإرسال عند حدوث خطأ؟

ثلاث محاولات مع تأخير أسّي: بعد دقيقة واحدة، ثم بعد 5 دقائق، ثم بعد 30 دقيقة. إذا فشلت جميع المحاولات الثلاث -- يُعلَّم الحدث كـ failed.

كيف يمكن التحقق من توقيع الويب هوك؟

احسب HMAC-SHA256 لجسم الطلب باستخدام webhook secret الخاص بك وقارنه مع رأس X-Tikento-Signature. استخدم مقارنة ذات وقت ثابت (constant-time) للحماية من هجمات التوقيت.

هل يمكن إعداد عدة عناوين URL للويب هوكس؟

نعم. في قسم الإعدادات - التكاملات يمكنك إضافة عدة عناوين URL واختيار أنواع الأحداث التي تُرسل إلى كل منها.

الويب هوكس: الأحداث والتحقق من التوقيع

نظرة عامة

تتيح لك الويب هوكس تلقي إشعارات حول الأحداث على منصة tikento في الوقت الفعلي. عند وقوع حدث (تسجيل جديد، دفع ناجح، إلغاء فعالية) يرسل tikento طلب HTTP POST إلى عنوان URL الخاص بك مع بيانات الحدث.

الويب هوكس متاحة في خطط Pro وBusiness وEnterprise.

الإعداد

إضافة عنوان URL للويب هوك

افتح الإعدادات في القائمة الجانبية.
انتقل إلى قسم «التكاملات».
اضغط على «إضافة ويب هوك».
أدخل عنوان URL لنقطة النهاية (HTTPS مطلوب).
اختر أنواع الأحداث التي تريد تلقيها.
اضغط على «حفظ».

بعد الحفظ سيرسل tikento طلب اختبار إلى العنوان المحدد للتحقق من التوفر.

Webhook secret

عند إنشاء ويب هوك سيولّد النظام webhook secret -- سلسلة نصية للتحقق من التوقيع. احفظه في مكان آمن. يُعرض السر مرة واحدة فقط.

أنواع الأحداث

الحدث	الوصف
`registration.created`	تم إنشاء تسجيل جديد
`registration.updated`	تم تحديث بيانات التسجيل (الحالة، الحقول)
`payment.completed`	تم إتمام الدفع بنجاح
`payment.refunded`	تم إجراء استرداد المبلغ
`event.published`	تم نشر الفعالية
`event.cancelled`	تم إلغاء الفعالية

يمكنك الاشتراك في جميع الأنواع أو اختيار ما تحتاجه فقط في إعدادات التكاملات.

تنسيق الحمولة

يُرسل كل ويب هوك كطلب HTTP POST بجسم بتنسيق JSON.

رؤوس الطلب

الرأس	الوصف
`Content-Type`	`application/json`
`X-Tikento-Event`	نوع الحدث (مثلاً `registration.created`)
`X-Tikento-Signature`	توقيع HMAC-SHA256 لجسم الطلب
`X-Tikento-Timestamp`	طابع زمني Unix للإرسال (بالثواني)
`X-Tikento-Request-Id`	معرف فريد للطلب

هيكل الجسم

{
  "event": "registration.created",
  "timestamp": "2026-06-30T14:30:00Z",
  "requestId": "req_01912345abcdef",
  "data": {
    "id": "01912345-6789-7abc-def0-123456789abc",
    "event_id": "01900000-0000-7000-0000-000000000001",
    "status": "registered",
    "fields": {
      "registrant_email": "user@example.com",
      "first_name": "Ivan",
      "last_name": "Petrov"
    },
    "created_at": "2026-06-30T14:30:00Z"
  }
}

حقل requestId موجود في كل ويب هوك. استخدمه لإزالة التكرار وعند التواصل مع الدعم الفني.

أمثلة على الحمولة حسب أنواع الأحداث

registration.created

{
  "event": "registration.created",
  "timestamp": "2026-06-30T14:30:00Z",
  "requestId": "req_01912345abcdef",
  "data": {
    "id": "01912345-6789-7abc-def0-123456789abc",
    "event_id": "01900000-0000-7000-0000-000000000001",
    "event_slug": "tech-conference-2026",
    "status": "registered",
    "ticket_definition_id": "01900000-0000-7000-0000-000000000010",
    "fields": {
      "registrant_email": "user@example.com",
      "first_name": "Ivan",
      "last_name": "Petrov",
      "company": "Acme Corp"
    },
    "created_at": "2026-06-30T14:30:00Z"
  }
}

payment.completed

{
  "event": "payment.completed",
  "timestamp": "2026-06-30T14:31:00Z",
  "requestId": "req_01912345abcdf0",
  "data": {
    "id": "01912345-6789-7abc-def0-000000000099",
    "registration_id": "01912345-6789-7abc-def0-123456789abc",
    "amount": 5000,
    "currency": "RUB",
    "method": "card",
    "gateway": "yookassa",
    "idempotency_key": "idem_abc123",
    "completed_at": "2026-06-30T14:31:00Z"
  }
}

event.cancelled

{
  "event": "event.cancelled",
  "timestamp": "2026-06-30T15:00:00Z",
  "requestId": "req_01912345abcdf1",
  "data": {
    "id": "01900000-0000-7000-0000-000000000001",
    "slug": "tech-conference-2026",
    "title": "Tech Conference 2026",
    "cancelled_at": "2026-06-30T15:00:00Z",
    "reason": "Venue unavailable"
  }
}

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

يُوقَّع كل ويب هوك باستخدام HMAC-SHA256. يضمن التحقق من التوقيع أن الطلب مُرسل من tikento وليس من مهاجم.

الخوارزمية

احصل على قيم الرأسين X-Tikento-Timestamp وX-Tikento-Signature.
كوّن سلسلة التوقيع: <timestamp>.<body>، حيث body هو الجسم الخام للطلب.
احسب HMAC-SHA256 من هذه السلسلة باستخدام webhook secret الخاص بك.
قارن النتيجة مع X-Tikento-Signature بتنسيق hex.

مثال بلغة Node.js

const crypto = require('crypto');

function verifySignature(body, timestamp, signature, secret) {
  const payload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // مقارنة ذات وقت ثابت للحماية من هجمات التوقيت
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

مثال بلغة Python

import hmac
import hashlib

def verify_signature(body: str, timestamp: str, signature: str, secret: str) -> bool:
    payload = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

الحماية من هجمات إعادة التشغيل

تحقق من X-Tikento-Timestamp: إذا كان أقدم من 5 دقائق -- ارفض الطلب. هذا يمنع إعادة استخدام الويب هوكس المعترضة.

سياسة إعادة المحاولة

إذا لم يستجب نقطة النهاية الخاصة بك بـ HTTP 2xx، يعيد tikento الإرسال:

المحاولة	التأخير
1	فوراً
2	بعد دقيقة واحدة
3	بعد 5 دقائق
4	بعد 30 دقيقة

إذا فشلت جميع المحاولات الأربع (الأولى + 3 إعادات) يُعلَّم الحدث كـ failed. ستجد قائمة الويب هوكس الفاشلة في قسم الإعدادات - التكاملات - سجل التسليم.

ما يُعتبر نجاحاً

HTTP 200، 201، 202، 204 -- يُعتبر التسليم ناجحاً.
المهلة: يجب استلام الاستجابة خلال 10 ثوانٍ.

ما يُعتبر خطأً

HTTP 4xx (باستثناء 410) -- إعادة إرسال، قد تكون هناك مشكلة من جانب المستلم.
HTTP 5xx -- إعادة إرسال مع تأخير.
انتهاء المهلة (لا استجابة خلال 10 ثوانٍ) -- إعادة إرسال.
HTTP 410 (Gone) -- يُعطَّل الويب هوك تلقائياً ولن تكون هناك إعادات.

إزالة التكرار

بسبب إعادة المحاولات قد تتلقى نقطة النهاية الخاصة بك نفس الحدث عدة مرات. استخدم requestId من الحمولة لإزالة التكرار:

عند تلقي ويب هوك تحقق مما إذا كنت قد عالجت requestId بالفعل.
إذا نعم -- أرجع HTTP 200 بدون معالجة مكررة.
إذا لا -- عالج الطلب واحفظ requestId.

استقبل الويب هوكس فقط عبر HTTPS.
تحقق دائماً من التوقيع عبر HMAC-SHA256.
تحقق من الطابع الزمني للحماية من هجمات إعادة التشغيل.
خزّن webhook secret في متغيرات البيئة وليس في الكود.