notpanel
الخدماتالأسعارالأسئلة الشائعةهداياAPI
notpanel

متابعون وإعجابات ومشاهدات لكل منصة.

يجمع الكتالوج بين خدمات نديرها مباشرة وسعة من شركاء موثوقين. يظهر التوفر والوقت وrefill وdrip-feed لكل خدمة؛ وتبقى مسارات التنفيذ وهوية الشركاء سرية.

المنتج

  • الخدمات
  • الأسعار
  • مؤشر الأسعار
  • برنامج الشركاء

الموارد

  • API
  • المدونة
  • الأسئلة الشائعة
  • الحالة

الشركة

  • من نحن
  • لماذا NotPanel
  • اتصل بنا

قانوني

  • شروط الخدمة
  • سياسة الخصوصية
  • سياسة الاسترداد

اللغات

  • English
  • Español
  • Português
  • Русский
  • Türkçe
  • العربية
  • हिन्दी
  • Bahasa Indonesia
  • Français
  • 中文

© 2026 NotPanel. جميع الحقوق محفوظة.

support@notpanel.com
notpanel
توثيق الواجهة
+
توثيق الواجهة

مقدمة

  • نظرة عامة
  • البدء
  • المصادقة
  • حدود المعدل
  • الأخطاء

الكتالوج

  • سرد الخدمات
  • الكتالوج المتقدم
  • أنواع الخدمات

الطلبات

  • تقديم طلب
  • حالة الطلب
  • تقدير الاسترداد
  • إعادة التعبئة
  • إلغاء

الحساب

  • حالة الحساب
  • الرصيد

الـ webhooks

  • إدارة الـ webhooks

المرجع

  • سجل التغييرات
  • مجموعات التطوير والمكتبات

تحتاج مساعدة؟

support@notpanel.com →

تسجيل webhook

يشترك عنوان URL عام في الأحداث المدعومة. تتلقى كل نقطة نهاية سر HMAC-SHA256 خاصًا بها يُعرض مرة واحدة عند الإنشاء. إذا فُقد، فاحذف نقطة النهاية وأضفها مجددًا.

POSThttps://notpanel.com/api/v3action=webhook.add
مفتاح API مطلوبمحدود بالمعدل (حساب مشترك + IP + إجراء)الجسم: application/x-www-form-urlencoded
حد أقصى 5 webhooks لكل مفتاح API. استخدم عنوان HTTPS متاحًا للعامة. تُرفض الوجهات غير الآمنة أو الخاصة أو loopback أو غير العامة بأي شكل آخر.

المعاملات

الاسمالنوعالوصف
keyمطلوبstringمفتاح API الخاص بك.
actionمطلوبstringيجب أن يكون السلسلة النصية الحرفية "webhook.add".
urlمطلوبstring (URL)نقطة نهاية HTTPS علنية ستستقبل طلبات POST. يجب أن تكون قابلة للوصول من الإنترنت العام.
eventsstring (CSV)مجموعة فرعية مفصولة بفواصل من الأحداث الستة المدعومة أدناه. احذفه للاشتراك في الأحداث الستة كلها.

مثال على الطلب

استبدل YOUR_API_KEY بالمفتاح المُولَّد ضمن صفحة API في لوحة تحكمك.

curl -X POST https://notpanel.com/api/v3 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=YOUR_API_KEY&action=webhook.add&url=https://your-server.example.com/notpanel-webhook&events=order.completed,order.refunded"
const res = await fetch("https://notpanel.com/api/v3", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    action: "webhook.add",
    url: "https://your-server.example.com/notpanel-webhook",
    events: "order.completed,order.refunded",
  }),
});

const data = await res.json();
console.log(data);
import requests

res = requests.post(
  "https://notpanel.com/api/v3",
  data={
    "key": "YOUR_API_KEY",
    "action": "webhook.add",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": "order.completed,order.refunded",
},
)
print(res.json())
<?php
$body = http_build_query([
    'key' => 'YOUR_API_KEY',
    'action' => 'webhook.add',
    'url' => 'https://your-server.example.com/notpanel-webhook',
    'events' => 'order.completed,order.refunded',
]);

$response = file_get_contents('https://notpanel.com/api/v3', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n",
        'content' => $body,
        'ignore_errors' => true,
    ],
]));

print_r(json_decode($response, true));

مثال على الاستجابة

{
  "webhook_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "url": "https://your-server.example.com/notpanel-webhook",
  "secret": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "events": [
    "order.completed",
    "order.refunded"
  ]
}

الأخطاء الشائعة

الحالةالجسمالسبب
400{"error":"Maximum 5 webhook endpoints per API key"}استنفدت نقاط النهاية القائمة الحد الأقصى. أزل نقطة نهاية غير مستخدمة عبر action=webhook.remove أولاً.
400{"error":"Webhook URL must be a publicly reachable HTTPS URL"}لم يكن الرابط عنوان HTTPS صالحًا، أو تعذّر تحليله، أو حُلّ إلى عنوان IP خاص/محلي (loopback).
400{"error":"Webhook event is invalid","error_code":"INVALID_WEBHOOK_EVENT"}اسم الحدث ليس ضمن قائمة السماح. تحقّق من الإملاء — تأخذ الأسماء الشكل "order.<status>".

الأحداث المتاحة

  • order.completed
  • order.partial
  • order.processing
  • order.in_progress
  • order.refunded
  • order.refill_completed

سرد الـ webhooks

يُرجع action=webhook.list كل نقطة نهاية مسجّلة تحت المفتاح المستدعي، بما في ذلك سلامة تسليمها (status، وfailureCount، وlastDeliveredAt).

key=YOUR_API_KEY&action=webhook.list
[
  {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": ["order.completed", "order.refunded"],
    "status": "active",
    "failureCount": 0,
    "lastDeliveredAt": "2026-04-30T15:42:11.000Z",
    "createdAt": "2026-04-15T09:01:00.000Z"
  }
]

إزالة webhook

يحذف action=webhook.remove مع UUID لنقطة النهاية تلك النقطة ويلغي سر التوقيع الخاص بها. قد يصل تسليم بدأ بالفعل؛ ولن توضع أحداث جديدة لها في الطابور.

key=YOUR_API_KEY&action=webhook.remove&id=3f2504e0-4f89-41d3-9a0c-0305e82c3301

{
  "success": true
}

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

كل تسليم هو POST مع Content-Type: application/json. يحتوي الجسم على events وtimestamp وdeliveryId. تجمع الإعدادات العامة الحالية لمدة تصل إلى 5 ثوانٍ وتتضمن 50 حدثًا كحد أقصى، ولكل منها id منطقي ثابت وevent وtimestamp وdata. قد تضيف قائمة الانتظار أو الأعطال تأخيرًا، لذا فهذا ليس وعدًا بالتسليم خلال 5 ثوانٍ. الترويسات:

  • X-Webhook-Signature — القيمة sha256=&lt;hex&gt; المحسوبة على &lt;timestamp&gt;.&lt;البايتات الدقيقة لجسم JSON&gt;.
  • X-Webhook-Timestamp — طابع Unix الزمني للتسليم بالثواني.
  • X-Webhook-Delivery-Id — UUID لحزمة التسليم ويعاد استخدامه عند إعادة محاولة الحزمة نفسها. لا توجد ترويسة حدث على مستوى التسليم؛ اقرأ كل حدث من الجسم.
{
  "events": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "event": "order.completed",
      "timestamp": 1777534931,
      "data": {
        "order": 7001,
        "orderId": 7001,
        "serviceId": 1,
        "status": "Completed",
        "status_key": "completed",
        "charge": "0.50",
        "startCount": 1234,
        "remains": 0
      }
    }
  ],
  "timestamp": 1777534931,
  "deliveryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

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

اقرأ X-Webhook-Timestamp وبايتات JSON المستلمة كما هي. احسب HMAC-SHA256 فوق &lt;timestamp&gt;.&lt;body bytes&gt; باستخدام السر، وصغه sha256=&lt;hex&gt; وقارنه بـX-Webhook-Signature بزمن ثابت. تحتفظ إعادة المحاولة بمعرفات الأحداث وdeliveryId، لكنها تحصل على timestamp وجسم وتوقيع جديد.

كسياسة خاصة بك لمنع إعادة التشغيل، يمكنك رفض تسليم صحيح التوقيع إذا اختلف طابعه الزمني عن ساعة خادمك بأكثر من 5 دقائق.

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

  • أفضل جهد مع إعادة المحاولة. تنهي استجابة 2xx عملية التسليم. تنتهي مهلة كل محاولة بعد 30 ثانية. قد تبدأ إعادة المحاولة بعد 5 ثوانٍ مع تأخير أُسّي أقصاه 5 دقائق، لكن لا يوجد ضمان دائم للتسليم مرة واحدة على الأقل.
  • حد الإيقاف المؤقت. تُوقَف نقطة النهاية بعد 10 محاولات فاشلة متتالية. لا توجد عملية تمكين أو تحديث؛ احذفها، ثم سجّل بديلًا باستخدام action=webhook.add واحفظ السر الجديد المعروض.
  • الترتيب غير مضمون. اجعل المعالجات متكافئة عند التكرار، وعالج كل حدث في الدفعة، وأزل تكرار الانتقال المنطقي بواسطة id الحدث أو الدفعة المعاد إرسالها بواسطة deliveryId، ووفّق الحالة المهمة باستخدام action=status.