वेबहुक और ईवेंट

रियल-टाइम ईवेंट। HMAC-साइन किए गए डिलीवर किए गए।

जैसे ही कोई दस्तावेज़, कार्य, वर्कस्पेस या कार्य बदलता है, PaperOffice आपके अंतर्बिंदु को कॉल करता है। कोई पॉलिंग नहीं।

22 ईवेंट प्रकार, HMAC-SHA256 साइनचर, तीन पुनः प्रयास रणनीतियाँ और प्रत्येक प्रयास के लिए एक डिलीवरी लॉग।

पहला Webhook सब्सक्राइब करना पहला API कॉल शुरू करना

प्रत्येक डिलीवरी पर HMAC-SHA256 अधिकतम 10 पुनरावृत्तियाँ (मानक 5) घटना-ID के अनुसार आइडेंपोटेंट

yourdomain.com/webhooks/paperoffice

POST /your-endpoint 200 OK HMAC-SHA256

अनुरोध हेडर

X-PaperOffice-Eventdocument.processed
X-PaperOffice-Event-IDa3b7f9c1d4e8b2a6
X-PaperOffice-Signaturesha256=9f8a2c…

JSON-बॉडी

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": { "pofid": "doc_01HZY8K3…" }
}

स्वयं की यूरोपीय संघ बुनियादी ढांचा आपका डेटा यूरोप में सुरक्षित रहता है।
ISO 27001 सक्रिय सुरक्षा प्रमाणित।
SOC 2 प्रकार II सक्रिय अंतर्राष्ट्रीय ऑडिट मानक।
24+ वर्षों का अनुभव परीक्षित। स्थिर। भविष्य-सुरक्षित।

उपलब्ध घटनाएँ

22 इवेंट प्रकार, एंटिटी के अनुसार समूहीकृत

व्यक्तिगत इवेंटों की सदस्यता लें या सभी के लिए * प्लेसहोल्डर का उपयोग करें।

दस्तावेज़

document.uploaded एक वर्कस्पेस में नया दस्तावेज़ अपलोड किया गया
document.created document.uploaded के लिए उपनाम (अनुकूलता)
document.processed OCR/AI-IDP पाइपलाइन सफलतापूर्वक पूर्ण हुई
document.edited दस्तावेज़ संपादित किया गया: मेटाडेटा, टैग या सामग्री अपडेट की गई
document.deleted दस्तावेज़ कूड़ेदान में डाला गया
document.restored कूड़ेदान से दस्तावेज़ पुनर्स्थापित किया गया
document.moved दस्तावेज़ वर्कस्पेस के बीच स्थानांतरित किया गया
document.version_created एक मौजूदा दस्तावेज़ का नया संस्करण
document.lifecycle_changed संरक्षण/अभिलेखागार स्थिति बदली गई
document.comment_added दस्तावेज़ पर टिप्पणी बनाई गई
document.note_added आंतरिक नोट संलग्न किया गया
document.tag_added टैग दस्तावेज़ को सौंपा गया
document.legal_hold_placed कानूनी हॉल सक्रिय (अपरिवर्तनीय)
document.legal_hold_released कानूनी हॉल समाप्त किया गया

जॉब्स

job.completed एसीनक्रोनस जॉब सफलतापूर्वक पूर्ण हुआ
job.failed एसीनक्रोनस जॉब अंततः विफल रहा
job.progress लंबे जॉब्स में प्रगति अद्यतन

Workspaces

workspace.shared वर्कस्पेस का उपयोगकर्ता या टीम के साथ साझा किया गया
workspace.unshared वर्कस्पेस तक पहुंच को खारिज कर दिया गया

कार्य

task.created नया कार्य बनाया गया
task.completed कार्य को पूरा किया गया के रूप में चिह्नित
task.overdue कार्य की नियत तिथि बीत गई

पेलोड और हेडर

प्रत्येक डिलीवरी एक ही स्कीमा का पालन करती है

पूर्वानुमानित JSON बॉडी, स्थिर HTTP हेडर, ISO-8601-UTC टाइमस्टैम्प।

अनुरोध बॉडी

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6c9f1d4e7b2a5c8f1",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": {
    "pofid": "doc_01HZY8K3M7P2Q9R5T1V6W4X2Y8",
    "workspace_id": 17,
    "filename": "invoice-2026-04-17.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284521,
    "processing_result": {
      "ocr_done": true,
      "classification": "invoice",
      "confidence": 0.98
    }
  }
}

HTTP अनुरोध हेडर

हेडर उदाहरण मान अर्थ

Content-Type application/json सदैव JSON, UTF-8 एन्कोडेड

User-Agent PaperOffice-Webhook/1.0 फायरवॉल अनुमति सूचियों के लिए स्थिर पहचानकर्ता

X-PaperOffice-Event document.processed प्रस्तुत घटना प्रकार

X-PaperOffice-Event-ID a3b7f9c1… 128-बिट अद्वितीय ID। इसे आत्मसमरूपता कुंजी के रूप में उपयोग करें।

X-PaperOffice-Subscription-ID 42 उस सब्सक्राइबर की ID जो ईवेंट प्राप्त करती है

X-PaperOffice-Signature sha256=… रॉ बॉडी का HMAC-SHA256, हेक्स-कोडित

cURL

1curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "My Production Webhook",6    "url": "https://yourdomain.com/webhooks/paperoffice",7    "events": ["document.processed", "job.completed", "job.failed"],8    "retry_policy": "exponential",9    "max_retries": 5,10    "timeout_ms": 1000011  }'

1import crypto from 'crypto';2import express from 'express';34const app = express();5const WEBHOOK_SECRET = process.env.PAPEROFFICE_WEBHOOK_SECRET;67app.post('/webhooks/paperoffice', express.raw({ type: 'application/json' }), (req, res) => {8  const signature = req.header('X-PaperOffice-Signature'); // "sha256=..."9  const eventId   = req.header('X-PaperOffice-Event-ID');10  const eventType = req.header('X-PaperOffice-Event');1112  const expected = 'sha256=' + crypto13    .createHmac('sha256', WEBHOOK_SECRET)14    .update(req.body)15    .digest('hex');1617  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {18    return res.status(401).send('invalid signature');19  }2021  const event = JSON.parse(req.body.toString());22  // store eventId as idempotency key -> never process the same ID twice23  console.log(eventType, event.data);24  res.status(200).send('ok');25});

1import hmac, hashlib, os2from flask import Flask, request, abort34app = Flask(__name__)5WEBHOOK_SECRET = os.environ["PAPEROFFICE_WEBHOOK_SECRET"]67@app.route("/webhooks/paperoffice", methods=["POST"])8def paperoffice_webhook():9    signature  = request.headers.get("X-PaperOffice-Signature", "")10    event_id   = request.headers.get("X-PaperOffice-Event-ID", "")11    event_type = request.headers.get("X-PaperOffice-Event", "")1213    expected = "sha256=" + hmac.new(14        WEBHOOK_SECRET.encode(),15        request.get_data(),16        hashlib.sha256,17    ).hexdigest()1819    if not hmac.compare_digest(signature, expected):20        abort(401)2122    payload = request.get_json()23    # store event_id as idempotency key in your DB24    print(event_type, payload["data"])25    return "ok", 200

1<?php2// PaperOffice webhook receiver with HMAC-SHA256 signature verification3$secret = getenv('PAPEROFFICE_WEBHOOK_SECRET');4$raw    = file_get_contents('php://input');56$signature  = $_SERVER['HTTP_X_PAPEROFFICE_SIGNATURE'] ?? '';7$event_id   = $_SERVER['HTTP_X_PAPEROFFICE_EVENT_ID'] ?? '';8$event_type = $_SERVER['HTTP_X_PAPEROFFICE_EVENT'] ?? '';910$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);11if (!hash_equals($expected, $signature)) {12    http_response_code(401);13    exit('invalid signature');14}1516$event = json_decode($raw, true);17// store event_id as idempotency key in your DB18error_log("{$event_type}: " . json_encode($event['data']));19http_response_code(200);20echo 'ok';

हस्ताक्षर सत्यापन

प्रत्येक डिलीवरी को HMAC-SHA256 के साथ सत्यापित करें

अपने साझा सीक्रेट का उपयोग करके रॉ अनुरोध बॉडी पर HMAC-SHA256 की गणना करें और परिणाम को X-PaperOffice-Signature से तुलना करें — स्थिर समय के साथ अनिवार्य रूप से।

स्थिर समय में तुलना
hash_equals, hmac.compare_digest या crypto.timingSafeEqual: तुलना को समय का अंतर नहीं दिखाना चाहिए।
रोहेन बॉडी पर हस्ताक्षर करें
हस्ताक्षर अपरिवर्तित अनुरोध बॉडी के लिए मान्य है। जांच के बाद ही JSON पार्स करें, अन्यथा हैश भिन्न होगा।
API द्वारा सदस्यता लें
name, url और events के साथ POST /latest/webhooks/subscribe करें। यदि secret खाली छोड़ दिया जाता है, तो PaperOffice इसे उत्पन्न करेगा और एक बार में वापस कर देगा।

प्रमाणीकरण और कुंजियाँ Postman संग्रह

पुनः प्रयास और डिलीवरी

अधिकतम 10 पुनरावृत्तियों के साथ तीन पुनः प्रयास रणनीतियाँ

प्रत्येक सदस्यता के लिए नीति चुनें। प्रत्येक प्रयास को स्थिति कोड, प्रतिक्रिया बॉडी और समय मापन के साथ लॉग किया जाएगा।

मानक exponential
घातांकीय (मानक)

प्रत्येक असफल प्रयास के बाद प्रयासों के बीच का अंतर दोगुना हो जाता है।
linear
रैखिक

प्रयासों के बीच का अंतर एक निश्चित चरण से बढ़ता है।
none
कोई नहीं

कोई पुनः प्रयास नहीं, यहां तक कि 5xx पर भी (भेजें और भूल जाएं)। टेस्ट हुक के लिए उपयोगी।

सफलता टाइमआउट विंडो के भीतर HTTP 2xx
अधिकतम पुनः प्रयास अधिकतम 10 पुनः प्रयास (डिफ़ॉल्ट 5)
समय सीमा समाप्त 1.000–30.000 मिलीसेकंड प्रति प्रयास (मानक 10,000)
डिलीवरी लॉग प्रत्येक प्रयास को लॉग किया जाता है; सब्सक्रिप्शन हटाने के बाद भी लॉग बना रहता है।

मैनेजमेंट-API

/latest/webhooks/ के तहत पांच एंडपॉइंट्स

सब्सक्रिप्शन बनाना, सूचीबद्ध करना, अपडेट करना और हटाना — इसके साथ एक परीक्षण एंडपॉइंट। प्रत्येक कॉल में बेयरर टोकन होता है।

POST /webhooks/subscribe सब्सक्रिप्शन बनाएं; पेलोड HMAC-SHA256 के साथ हस्ताक्षरित होते हैं MCP टूलpo-webhooks-subscribe
GET /webhooks/list खाते के सभी वेबहुक सब्सक्रिप्शन सूचीबद्ध करें MCP टूलpo-webhooks-list
POST /webhooks/update URL, इवेंट्स, हेडर, रीट्राई पॉलिसी या सक्रिय स्थिति को अपडेट करें MCP टूलpo-webhooks-update
POST /webhooks/delete सदस्यता हटाएं; डिलीवरी लॉग बनाए रखें MCP टूलpo-webhooks-delete
POST /webhooks/test सदस्यता को एक परीक्षण ईवेंट भेजें और डिलीवरी की जांच करें MCP टूलpo-webhooks-test

MCP सर्वर देखना Postman संग्रह

सुरक्षा

मूल से सुरक्षित

प्रत्येक डिलीवरी पर लागू होने वाले छह तंत्र — PaperOffice की ओर से और आपके द्वारा।

HMAC-SHA256
प्रत्येक डिलीवरी आपके सीक्रेट के साथ हस्ताक्षरित होती है। तुलना अनिवार्य रूप से स्थिर समय में होनी चाहिए।
SSRF सुरक्षा
ग्राहकता और डिसपैच के दौरान निजी और आंतरिक IP पते, लोकाहोस्ट और क्लाउड मेटाडेटा एंडपॉइंट्स को अवरुद्ध कर दिया जाता है।
DNS रीबाउंडिंग से सुरक्षित
डिसपैच के दौरान IP का पुनः सत्यापन किया जाता है और CURLOPT_RESOLVE के माध्यम से पिन कर दिया जाता है।
HTTPS की अनुशंसा की जाती है
http और https दोनों स्वीकार किए जाते हैं। उत्पादन संचालन के लिए हम HTTPS की अनुशंसा करते हैं।
इवेंट आईडी के माध्यम से आइडेंपोटेंसी
प्रत्येक डिलीवरी में एक अद्वितीय X-PaperOffice-Event-ID होती है। अपने पक्ष पर डुप्लिकेट हटाएं।
पूर्ण डिलीवरी लॉग
सभी प्रयासों को लॉग किया जाता है: स्थिति कोड, प्रतिक्रिया बॉडी, समय मापन, त्रुटि संदेश।

सीमाएं

प्रत्येक सदस्यता के लिए डिलीवरी व्यवहार कॉन्फ़िगर करने योग्य

सभी मानों को सदस्यता के आधार पर, खाते के आधार पर नहीं, बनाते समय या बाद में /webhooks/update के माध्यम से सेट करें।

0–10 प्रत्येक डिलीवरी के लिए पुनरावृत्तियाँ (डिफ़ॉल्ट 5)
1,000–30,000 मिलीसेकंड प्रत्येक प्रयास के लिए टाइमआउट (डिफ़ॉल्ट 10,000)
3 रिपॉलिसी: कोई नहीं, रैखिक, घातांकीय
HMAC-SHA256 प्रत्येक डिलीवरी पर हस्ताक्षर

वेबहुक Professional प्लान से उपलब्ध हैं। आपकी सेटअप के लिए कौन सा प्लान उपयुक्त है, यह मूल्य अवलोकन दिखाता है।

मूल्य देखना प्रमाणीकरण और कुंजियाँ

वीडियो

क्रिया में वेबहुक

देखें कि PaperOffice वेबहुक व्यावहारिक रूप से कैसे काम करते हैं — वीडियो में।

प्रश्न

Webhooks से संबंधित सामान्य प्रश्न

मैं डिलीवरी की पुष्टि कैसे करूं?

अपने सब्सक्रिप्शन के सीक्रेट का उपयोग करके कच्चे रिक्वेस्ट बॉडी पर HMAC-SHA256 की गणना करें और परिणाम को स्थिर समय में X-PaperOffice-Signature हेडर (फॉर्मेट sha256=<hex>) से तुलना करें। यदि सिग्नेचर मेल नहीं खाता, तो HTTP 401 के साथ उत्तर दें और बॉडी को प्रोसेस न करें।

सीक्रेट कहाँ से आता है?

POST /latest/webhooks/subscribe के माध्यम से सब्सक्रिप्शन बनाते समय। यदि सीक्रेट फ़ील्ड खाली छोड़ दिया जाता है, तो PaperOffice एक सीक्रेट उत्पन्न करेगा और इसे एक बार रिस्पॉन्स में वापस कर देगा। POST /latest/webhooks/update के माध्यम से आप इसे किसी भी समय बदल सकते हैं।

यदि मेरा एंडपॉइंट उत्तर नहीं देता तो क्या होता है?

HTTP 2xx के बाहर की कोई भी प्रतिक्रिया या टाइमआउट को विफल प्रयास माना जाता है। पुनः प्रयास नीति (घातांकीय, रैखिक, कोई नहीं) के आधार पर, PaperOffice निर्धारित पुनः प्रयासों की संख्या (0–10, डिफ़ॉल्ट 5) तक डिलीवरी को दोहराता है। प्रत्येक प्रयास डिलीवरी लॉग में स्थिति कोड, प्रतिक्रिया और समय मापन के साथ दर्ज होता है।

क्या एक ही डिलीवरी दो बार प्राप्त हो सकती है?

हाँ, टाइमआउट के बाद पुनः प्रयासों के दौरान यह संभव है। इसलिए X-PaperOffice-Event-ID के माध्यम से डुप्लिकेट हटाएं: ID प्रत्येक घटना के लिए अद्वितीय होती है और आपकी डेटाबेस में आइडेंपोटेंसी कुंजी के रूप में उपयुक्त है।

मैं किन घटनाओं (events) को सब्सक्राइब कर सकता हूं?

चार समूहों से 22 घटना प्रकार: दस्तावेज़, कार्य, वर्कस्पेस और कार्य। आप व्यक्तिगत घटनाओं को या विल्डकार्ड * का उपयोग करके सभी को सब्सक्राइब करते हैं। फ़िल्टर (जैसे workspace_id या pofid) के माध्यम से आप एक सब्सक्रिप्शन को अतिरिक्त रूप से सीमित कर सकते हैं।

वेबहुक किस प्लान में शामिल हैं?

वेबहुक Professional प्लान से उपलब्ध हैं। आपकी सेटअप के लिए कौन सा प्लान उपयुक्त है, यह मूल्य अवलोकन दिखाता है।

संचालन और विश्वास

पहले कॉल से पहले एंटरप्राइज़ टीमें क्या जांचती हैं

अनुबंध, सुरक्षा, सहायता और सीमाएं, सब एक ही स्थान पर लिंक किए गए।

अगला स्टेशन

आगे कैसे बढ़ें

डेवलपर फनल में अनुशंसित अगला कदम और दो उपयुक्त शाखाएं।

Postman CollectionPostman में आयात करें, परीक्षण करें और डिबग करें Publishable KeysAI आर्टिफैक्ट्स और फ्रंटएंड ऐप्स के लिए ब्राउज़र-सुरक्षित कुंजियाँ पहला API कॉलकुंजी प्राप्त करें, अनुरोध भेजें, प्रतिक्रिया जांचें

डेवलपर प्रवेश पर वापस

14 मिनट में PaperOffice AI को समझें।

PaperOffice का उपयोग आप कैसे करना चाहेंगे?