API से प्रकाशन

अपनी वेबसाइट पर लेख सहेजने और प्रकाशित करने वाला रिसीवर बनाएं। CMS सेटिंग में एंडपॉइंट और साझा सीक्रेट जोड़ें। जाँचें और सहेजें से खाली डेटा वाला connection.test भेजा जाता है; HTTP 200 और ok: true लौटाएं। केवल मालिक और व्यवस्थापक कनेक्शन बदल सकते हैं।

सार्वजनिक HTTPS एंडपॉइंट इस्तेमाल करें जिसमें क्वेरी पैरामीटर, फ़्रैगमेंट या एम्बेड किए गए क्रेडेंशियल न हों।

एक रैंडम सीक्रेट तैयार है। आप इसकी जगह 32 से 256 अक्षरों का अपना सीक्रेट रख सकते हैं। इसे रिसीवर में कॉपी करें और सर्वर पर सुरक्षित रखें।

{
  "version": 1,
  "event": "connection.test",
  "id": "<event-id>",
  "data": {}
}

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true }

टेस्ट करके सहेजते समय रिसीवर को पुराने और नए दोनों सीक्रेट स्वीकार करने दें। Papigrows सहेजे हुए सीक्रेट का उपयोग तब तक करता है जब तक नया कनेक्शन टेस्ट में सफल होकर सहेजा नहीं जाता। जारी डिलीवरी पूरी होने के बाद पुराना सीक्रेट हटाएँ।

ये हेडर कनेक्शन परीक्षण और लेख डिलीवरी दोनों के साथ भेजे जाते हैं। हेडर नामों में छोटे-बड़े अक्षरों का अंतर नहीं होता।

JSON पार्स करने से पहले टाइमस्टैम्प, एक बिंदु और ठीक उसी मूल बॉडी पर v1 HMAC-SHA256 हस्ताक्षर सत्यापित करें। स्थिर समय में तुलना करें, पाँच मिनट से पुराने या भविष्य के टाइमस्टैम्प अस्वीकार करें और सीक्रेट सर्वर पर रखें। HTTPS और हस्ताक्षर डुप्लिकेट सुरक्षा का विकल्प नहीं हैं।

ये फ़ील्ड article.upsert बताते हैं। connection.test के लिए data खाली होता है। एनवेलप का प्रोटोकॉल संस्करण लेख के सामग्री संस्करण से अलग है।

संस्करण 2 में सादा पाठ, कार्यक्षेत्र और लक्षित समूह की आईडी, सारांश, अनुभाग और टैग शामिल हैं। कनेक्शन परीक्षण में रिसीवर को संस्करण 2 की स्पष्ट पुष्टि करनी होगी। मौजूदा रिसीवर संस्करण 1 पर बने रहते हैं, जब तक आप दूसरा संस्करण चुनकर सफल परीक्षण के बाद उसे सहेज नहीं लेते।

{
  "version": 2,
  "event": "connection.test",
  "id": "<event-id>",
  "data": {}
}

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true, "version": 2 }

POST /your-publishing-endpoint
Content-Type: application/json
X-Papigrows-Event-Id: <event-id>
X-Papigrows-Timestamp: <unix-seconds>
X-Papigrows-Signature: v1=<hex-hmac-sha256>
Idempotency-Key: <event-id>

{
  "version": 2,
  "event": "article.upsert",
  "id": "<event-id>",
  "data": {
    "id": "<permanent-article-id>",
    "groupId": "<permanent-article-group-id>",
    "workspaceId": "<owning-workspace-id>",
    "primaryAudienceId": "<saved-audience-id>",
    "businessAreaId": "<saved-business-area-id>",
    "text": "...",
    "summary": "...",
    "section": "Advice",
    "tags": ["Families"],
    "version": 7,
    "title": "Example",
    "html": "<p>...</p>",
    "slug": "example",
    "excerpt": "...",
    "coverImageUrl": "https://example.com/cover.jpg",
    "locale": "en",
    "hreflangAlternates": [
      { "locale": "sv", "url": "https://example.com/sv/blog/example" }
    ]
  }
}

संस्करण 2 मूल लेख फ़ील्ड बनाए रखता है और ये आवश्यक फ़ील्ड जोड़ता है। बिना सहेजे लक्ष्यीकरण वाले पुराने लेखों में लक्षित समूह की आईडी null रहती है।

प्रकाशित लेख सार्वजनिक करने के लिए Papigrows API कनेक्शन चालू करें। स्पष्ट रूप से संस्करण 2 माँगें; संस्करण न देने पर मूल उत्तर बना रहता है। निजी कार्यक्षेत्र और अप्रकाशित लेख उपलब्ध नहीं होते।

/api/content/feed/<workspace-slug>?version=2&locale=en&limit=20

हर लेख में सहेजी गई आईडी, सामग्री संस्करण, सादा पाठ और सारांश शामिल हैं। अनुभाग और टैग केवल प्रकाशन के समय दर्ज गंतव्य से आते हैं। यह रिकॉर्ड न मिलने पर टैग null होते हैं। हर कर्सर अनुरोध में version=2 और locale बनाए रखें।

सार्वजनिक फ़ीड में रूपांतरण उपलब्ध न होने पर text null होता है। 1 MiB से अधिक होने पर textUnavailable body_too_large और रूपांतरण त्रुटि पर conversion_failed होता है; अन्यथा null। HTML और पृष्ठ क्रम सुरक्षित रहते हैं।

लेख वास्तव में सार्वजनिक होने के बाद HTTP 200 या 201, वही ID, status published और सार्वजनिक HTTPS URL लौटाएं। कतार की पुष्टि, HTTP 202 या 204, रीडायरेक्ट, ड्राफ़्ट या अमान्य उत्तर प्रकाशन नहीं माने जाते। सहेजने और प्रकाशित करने से पहले सफलता न बताएं।

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "<permanent-article-id>",
  "status": "published",
  "url": "https://example.com/blog/example"
}

article.upsert, data.id को स्थायी कुंजी मानकर एक भाषा संस्करण बनाता या बदलता है। data.version और इवेंट ID को बदलाव के साथ एक ही परमाणु क्रिया में सहेजें। डुप्लिकेट पर सहेजी पुष्टि लौटाएं; पुराने संस्करण नए कंटेंट को कभी न बदलें। अधिकतम तीन प्रयास होते हैं, हर प्रयास की सीमा पाँच सेकंड है। नेटवर्क त्रुटि, HTTP 429 और HTTP 5xx पर 250 मिलीसेकंड और 1 सेकंड बाद पुनः प्रयास होता है। बॉडी और इवेंट ID वही रहते हैं; टाइमस्टैम्प और हस्ताक्षर नए होते हैं।

डिलीवरी बॉडी की सीमा 1 MiB और JSON प्रतिक्रिया की सीमा 16 KiB है। पार्स करने से पहले कच्ची अनुरोध बॉडी का आकार सीमित करें।

इस इंटीग्रेशन का दायरा

केवल लेख और Papigrows से फिर प्रकाशित किए गए संपादन। विषय या हटाने के इवेंट, पृष्ठभूमि कतार और बाहरी संपादन पढ़ना शामिल नहीं है। ईमेल के उत्तर से संपादन webhook को सुरक्षित रूप से अपडेट नहीं कर सकता; Papigrows में संपादित और प्रकाशित करें। मौजूदा योजना, गुणवत्ता और स्वचालित प्रकाशन सेटिंग लागू रहती हैं। अनिश्चित विफलता के बाद मैन्युअल पुनः प्रयास से पहले रिसीवर जाँचें; अनंत पुनः प्रयास नहीं होते।

यह Node.js सहायक केवल प्रामाणिकता जाँचता है। रिसीवर को अनुरोध आकार सीमित करना, इवेंट स्कीमा जाँचना, स्थायी स्टोरेज में डुप्लिकेट और संस्करण संभालना, लेख प्रकाशित करना और नीचे दी पुष्टि लौटाना भी आवश्यक है।

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

export function verifyWebhook(headers, rawBody, secret) {
  const timestamp = headers.get("x-papigrows-timestamp") ?? "";
  const signature = headers.get("x-papigrows-signature") ?? "";
  if (!/^\d{10}$/.test(timestamp)) return false;
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (age < 0 || age > 300) return false;
  if (!/^v1=[a-f0-9]{64}$/.test(signature)) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  const received = Buffer.from(signature.slice(3), "hex");
  if (received.length !== expected.length
    || !timingSafeEqual(received, expected)) return false;
  try {
    const event = JSON.parse(rawBody.toString());
    return typeof event.id === "string"
      && /^[a-f0-9]{64}$/.test(event.id)
      && headers.get("x-papigrows-event-id") === event.id
      && headers.get("idempotency-key") === event.id;
  } catch { return false; }
}