وثائق ناشر

الويب هوكس

استقبل أحداث ناشر في أنظمتك مع توقيع HMAC موثوق، وتحقّق منه بأمان.

يرسل ناشر أحداثًا موقّعة إلى الروابط التي تسجّلها، فتبقى أنظمتك متزامنة مع ما يحدث فعلًا. متاح في باقتَي الفِرق والوكالات.

تسجيل رابط

من الإعدادات ← المطوّرون ← الويب هوكس، أو برمجيًا:

curl -X POST https://api.naasher.com/api/sdk/v1/webhooks \
  -H "x-naasher-api-key: $NAASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/naasher", "events": ["post.published", "post.failed"] }'

عند الإنشاء نعرض سرّ التوقيع مرة واحدة — احفظه.

الأحداث

الحدثمتى يُرسل
post.createdأُنشئ منشور
post.scheduledجُدول منشور
post.publishingبدأ النشر إلى المنصّات
post.publishedنُشر بنجاح
post.failedفشل النشر
post.deletedحُذف منشور
channel.connectedرُبط حساب
channel.disconnectedفُصل حساب
channel.token_expiringرمز الحساب يقارب الانتهاء
channel.token_expiredانتهت صلاحية الرمز — يحتاج إعادة ربط
inbox.comment_receivedوصل تعليق جديد
report.weeklyالتقرير الأسبوعي جاهز
queue.lowطابور النشر شارف على النفاد
webhook.testاختبار يدوي من اللوحة

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

كل طلب يحمل ترويسة Naasher-Signature بالشكل:

t=1752163200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

التوقيع هو HMAC-SHA256 على النص "{timestamp}.{raw_body}" بسرّك. تحقّق منه بمقارنة ثابتة الزمن، وارفض الطلب إن كان الطابع الزمني قديمًا (نافذة خمس دقائق مثال جيد):

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyNaasherWebhook(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  const want = Buffer.from(expected, 'hex');
  return given.length === want.length && timingSafeEqual(given, want);
}

وقّع على الجسم الخام

احسب التوقيع على نص الطلب الخام قبل أي تحليل JSON — إعادة ترتيب المفاتيح تُبطل التوقيع.

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

نعيد المحاولة تلقائيًا عند فشل التسليم (رمز ‎5xx‎ أو انقطاع الشبكة) بتباعد متزايد. أعِد 2xx بسرعة ثم عالج الحدث لاحقًا؛ المهلة قصيرة عمدًا.