Next.js والمواقع المخصصة (webhook)

إذا كان موقعك تطبيق Next.js، أو واجهة أمامية منفصلة (headless)، أو أي شيء آخر بلا واجهة API للمحتوى، فيستطيع Clodix إرسال كل مقال منشور بصيغة JSON عبر POST إلى عنوان URL تتحكم فيه. هذا هو التكامل المناسب للمواقع المبنية خصيصًا، كما يعمل جيدًا كمحفّز لـ Zapier أو Make.

اربطه

1. افتح Settings → Publishing integrations وانقر على Next.js / Webhook.
2. املأ:
   • Webhook URL: عنوان https:// على خادمك يقبل طلب POST.
   • Signing secret (اختياري): اضبط واحدًا فيوقّع Clodix كل طلب لتتحقق أنه جاء منا فعلًا.
3. انقر على Connect. يرسل Clodix اختبار اتصال فورًا، ويجب أن ترد نقطة النهاية لديك بحالة 2xx لينجح الاتصال.

الحمولة

يُرسَل كل طلب بطريقة POST بصيغة JSON مع الترويسة content-type: application/json. يحتوي الغلاف دائمًا على الحقل event، ويعتمد شكل المتن على الحدث.

article.published: يُرسَل عندما يصبح المقال منشورًا:

{
  "event": "article.published",
  "article": {
    "title": "Best pour over coffee makers in 2026",
    "slug": "best-pour-over",
    "bodyHtml": "<p>...</p>",
    "metaDescription": "A guide to the best pour over coffee makers.",
    "imageUrl": "https://cdn.clodix.ai/covers/best-pour-over.jpg",
    "publishedAt": "2026-08-01T10:00:00.000Z"
  }
}

لا تُضمَّن metaDescription وimageUrl وpublishedAt إلا إذا كانت موجودة في المقال.

article.unpublished: يُرسَل عندما تلغي نشر مقال:

{ "event": "article.unpublished", "article": { "slug": "best-pour-over" } }

clodix.ping: اختبار الاتصال الذي يُرسَل مرة واحدة عند النقر على Connect:

{ "event": "clodix.ping" }

الترويسات

الترويسة	القيمة
content-type	application/json
x-clodix-event	القيمة نفسها للحقل event في المتن.
x-clodix-signature	تُرسَل فقط عند ضبط signing secret، انظر أدناه.

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

عند ضبط signing secret، يوقّع Clodix متن الطلب الخام كما هو تمامًا باستخدام HMAC-SHA256 بمفتاح هو السر الخاص بك، ويرسله في الترويسة x-clodix-signature: sha256=<hex digest>.

// app/api/clodix/route.ts
import { createHmac, timingSafeEqual } from "crypto";
import { NextRequest, NextResponse } from "next/server";

const SECRET = process.env.CLODIX_WEBHOOK_SECRET!;

export async function POST(req: NextRequest) {
  const rawBody = await req.text(); // read as text BEFORE parsing JSON
  const signature = req.headers.get("x-clodix-signature") ?? "";

  const expected =
    "sha256=" + createHmac("sha256", SECRET).update(rawBody).digest("hex");

  const ok =
    signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!ok) {
    return NextResponse.json({ error: "invalid signature" }, { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  // payload.event is "article.published" | "article.unpublished" | "clodix.ping"
  // ... upsert payload.article into your database/CMS by slug ...

  return NextResponse.json({ ok: true });
}

الرد بحالة 2xx

يجب أن ترد نقطة النهاية لديك بحالة نجاح (200–299) ليحتسب Clodix النشر ناجحًا، بما في ذلك اختبار الاتصال. الرد بحالة غير 2xx (أو عدم الرد إطلاقًا) يُعدّ نشرًا فاشلًا: يبقى المقال مسودة في Clodix، وتعرض شاشة الربط (أو زر Publish الخاص بالمقال) الحالة التي أعادتها نقطة النهاية فعليًا.

يجب أن يكون لنقطة النهاية عنوان عام على منافذ الويب القياسية (https://… أو http://… دون :port). أما العنوان الواقع في شبكة محلية أو خاصة، أو الذي يعيد التوجيه إليها، فيُرفض برسالة «This address isn't reachable from Clodix» قبل إرسال أي شيء إليه.

إعادة رابط حي (اختياري)

إذا ردّت نقطة النهاية لديك بـ { "url": "https://yoursite.com/blog/best-pour-over" }، فإن Clodix يخزّنه كعنوان URL المنشور للمقال ويستخدمه لإبلاغ محركات البحث بأن الصفحة جديدة. هذا اختياري، ويمكن لنقطة النهاية ببساطة أن ترد بـ { "ok": true } دون عنوان URL.

الأسئلة الشائعة

هل أحتاج إلى signing secret؟

هو اختياري لكنه موصى به لأي شيء مكشوف للعموم، فهو الطريقة الوحيدة التي تتأكد بها نقطة النهاية لديك أن الطلب جاء فعلًا من Clodix وليس من شخص خمّن عنوانك.

ماذا يحدث إذا كان خادمي متوقفًا عندما يحاول Clodix النشر؟

يفشل النشر ويبقى المقال مسودة. راجع مشكلات النشر لمعرفة ما سيفعله Clodix بعد ذلك وكيف تعيد المحاولة بأمان.

هل يمكنني استخدام هذا مع Zapier أو Make بدلًا من خادمي؟

نعم، الصق عنوان webhook الذي يعطيه لك Zapier أو Make لمحفّز «Catch Hook» / «Custom Webhook» في الحقل Webhook URL، وابنِ أتمتتك من هناك.

ذات صلة

• ربط موقعك
• مشكلات النشر
• نشر مقال