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

لوحة SMM الحديثة وبأسعار مناسبة. أسعار جملة مع تكامل مباشر مع المزوّدين.

المنتج

  • الخدمات
  • الأسعار
  • برنامج الشركاء
  • لماذا NotPanel
  • من نحن
  • المطورون
  • المدونة
  • الأسئلة الشائعة

قانوني

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

تواصل

  • اتصل بنا
  • support@notpanel.com

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

توثيق الواجهة
+
توثيق الواجهة

مقدمة

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

الكتالوج

  • سرد الخدمات

الطلبات

  • تقديم طلب
  • حالة الطلب
  • إعادة التعبئة

الحساب

  • الرصيد

الـ webhooks

  • إدارة الـ webhooks

المرجع

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

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

support@notpanel.com →

تسجيل webhook

يشترك برابط علني في حدث واحد أو أكثر. تتلقى كل نقطة نهاية سرّها الخاص بـ HMAC-SHA256 — يُستخدم لتوقيع كل عملية تسليم صادرة، مع حماية بنافذة مضادة للإعادة. يُعرض السر مرة واحدة عند الإنشاء؛ فإن فقدته، أعِد توليده بإزالة نقطة النهاية وإعادة إضافتها.

POSThttps://notpanel.com/api/v2action=webhook.add
مفتاح API مطلوبخاضع لحدّ المعدل (لكل مفتاح + لكل طبقة + لكل عنوان IP)الجسم: application/x-www-form-urlencoded
حد أقصى 5 webhooks لكل مفتاح API. يجب أن تكون عناوين URL قابلة للوصول علنياً، وأن تكون https (يُقبل http في بيئة التطوير فقط)، وألا تُحلَّل إلى عناوين IP خاصة/محلية (loopback) — فنحن نُجري تحليل DNS وقت التسجيل ونرفض العناوين الداخلية لمنع هجمات SSRF.

المعاملات

الاسمالنوعالوصف
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/v2 \
  -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.failed,balance.low"
const res = await fetch("https://notpanel.com/api/v2", {
  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.failed,balance.low",
  }),
});

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

res = requests.post(
  "https://notpanel.com/api/v2",
  data={
    "key": "YOUR_API_KEY",
    "action": "webhook.add",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": "order.completed,order.failed,balance.low",
},
)
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.failed,balance.low',
]);

$response = file_get_contents('https://notpanel.com/api/v2', 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": "whk_01HG9X...",
  "url": "https://your-server.example.com/notpanel-webhook",
  "secret": "rotate-this-immediately-it-is-shown-once",
  "events": [
    "order.completed",
    "order.partial",
    "order.cancelled",
    "order.expired",
    "order.failed",
    "order.processing",
    "order.in_progress",
    "order.refunded",
    "order.refill_completed",
    "balance.low"
  ]
}

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

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

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

  • order.completed
  • order.partial
  • order.cancelled
  • order.expired
  • order.failed
  • order.processing
  • order.in_progress
  • order.refunded
  • order.refill_completed
  • balance.low

سرد الـ webhooks

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

[
  {
    "id": "whk_01HG9X...",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": ["order.completed", "order.failed", "balance.low"],
    "status": "active",
    "failureCount": 0,
    "lastDeliveredAt": "2026-04-30T15:42:11.000Z",
    "createdAt": "2026-04-15T09:01:00.000Z"
  }
]

إزالة webhook

يزيل action=webhook.remove مع id=whk_... نقطة النهاية ويُبطل سرّ توقيعها. قد تصل عمليات التسليم الجارية التي سبق إدراجها في الطابور؛ أما الأحداث الجديدة فلن تُرسل.

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

كل عملية تسليم هي POST إلى عنوان URL المسجَّل لديك بترويسة Content-Type: application/json. تتضمن الترويسات:

  • X-NotPanel-Signature — قيمة HMAC-SHA256 لجسم الطلب الخام، مُرمّزة بالنظام الست عشري.
  • X-NotPanel-Timestamp — طابع زمني Unix (بالثواني). ارفض عمليات التسليم التي مضى عليها أكثر من 5 دقائق لإحباط هجمات الإعادة.
  • X-NotPanel-Event — اسم الحدث (يعكس event في الجسم).
{
  "event": "order.completed",
  "order_id": "ord_01HG9X7KJP4N...",
  "service_id": 1,
  "status": "completed",
  "charge": "0.50",
  "start_count": 1234,
  "remains": 0,
  "completed_at": "2026-04-30T15:42:11.000Z"
}

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

عند الاستلام: احسب قيمة HMAC-SHA256 للجسم الخام باستخدام السرّ الذي تلقيته عند التسجيل، ورمّزها بالنظام الست عشري، وقارنها بـ X-NotPanel-Signature باستخدام مقارنة ثابتة الزمن (مثل crypto.timingSafeEqual في Node). ارفض الطلب إن لم تتطابقا — فالمهاجم الذي يخمّن عنوان URL لكن ليس سرّك لا يستطيع تزوير طلب صالح.

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

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

  • مرة واحدة على الأقل. تُعدّ استجابات 2xx الناجحة مُسلَّمة. أما أي شيء آخر فتُعاد محاولته بتراجع أُسّي (1m ← 5m ← 30m ← 2h ← 12h) حتى تنجح نقطة النهاية أو تستنفد المحاولات.
  • عتبة التعطيل. بعد 20 إخفاقًا متتاليًا، تُعطَّل نقطة النهاية تلقائيًا. أعِد تفعيلها من لوحة التحكم أو بإعادة تسجيلها.
  • الترتيب غير مضمون. قد يصل حدثان للطلب نفسه بترتيب مختلف أثناء إعادة المحاولة. استخدم X-NotPanel-Timestamp وحمولة الحدث للمطابقة.