Webhooks والأحداث

أحداث في الوقت الفعلي. تم التسليم بتوقيع HMAC.

يقوم PaperOffice باستدعاء نقطة النهاية الخاصة بك بمجرد حدوث أي تغيير في مستند أو مهمة أو مساحة عمل أو مهمة. لا حاجة للاستعلام المستمر (Polling).

22 نوعًا من الأحداث، توقيع HMAC-SHA256، ثلاث استراتيجيات إعادة محاولة وسجل تسليم لكل محاولة.

الاشتراك في أول Webhook بدء أول استدعاء لـ API

HMAC-SHA256 مع كل عملية تسليم حتى 10 تكرارات (الافتراضي 5) متطابق حسب معرّف الحدث

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 النوع الثاني نشط معايير التدقيق الدولية.
أكثر من 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 تم تعيين علامة (Tag) لمستند
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 بت. استخدمه كمفتاح لتكرار الطلبات.

X-PaperOffice-Subscription-ID 42 معرف الاشتراك الذي يستقبل الحدث

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
POST /latest/webhooks/subscribe مع name, url و events. إذا تركت secret فارغًا، سيقوم PaperOffice بإنشائه وإرجاعه مرة واحدة فقط.

المصادقة والمفاتيح مجموعة Postman

إعادة المحاولة والتوصيل

ثلاث استراتيجيات إعادة محاولة، حتى 10 تكرارات

اختر السياسة لكل اشتراك. يتم تسجيل كل محاولة مع رمز الحالة، جسم الاستجابة وقياس الوقت.

الافتراضي exponential
أسي (افتراضي)

يتضاعف الفاصل الزمني بين المحاولات بعد كل محاولة فاشلة.
linear
خطي

يزيد الفاصل الزمني بين المحاولات بخطوة ثابتة.
none
بدون

لا إعادة محاولة، حتى في حالة أخطاء 5xx (إرسال ونسيان). مفيد لخطافات الاختبار.

نجاح HTTP 2xx ضمن نافذة المهلة الزمنية
الحد الأقصى لإعادة المحاولات حتى 10 إعادة محاولة (الافتراضي 5)
مهلة زمنية 1000–30000 مللي ثانية لكل محاولة (الافتراضي 10000)
سجل التسليم يتم تسجيل كل محاولة؛ ويبقى السجل محفوظًا حتى بعد حذف الاشتراك.

إدارة-API

خمسة نقاط نهاية تحت /latest/webhooks/

إنشاء الاشتراكات وعرضها وتحديثها وحذفها — بالإضافة إلى نقطة نهاية للاختبار. كل استدعاء يحمل رمز حامل (Bearer Token).

POST /webhooks/subscribe إنشاء اشتراك؛ يتم توقيع حمولات البيانات باستخدام HMAC-SHA256 أداة MCPpo-webhooks-subscribe
GET /webhooks/list عرض جميع اشتراكات الويب هوك الخاصة بالحساب أداة MCPpo-webhooks-list
POST /webhooks/update تحديث عنوان URL، الأحداث، الرؤوس، سياسة إعادة المحاولة أو الحالة النشطة أداة MCPpo-webhooks-update
POST /webhooks/delete حذف الاشتراك؛ يبقى سجل التسليم ساريًا أداة MCPpo-webhooks-delete
POST /webhooks/test إرسال حدث اختبار إلى اشتراك والتحقق من التسليم أداة MCPpo-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 سياسات إعادة المحاولة: none، linear، exponential
HMAC-SHA256 توقيع مع كل تسليم

تتوفر Webhooks بدءًا من الخطة Professional. يعرض ملخص الأسعار الخطة المناسبة لإعدادك.

عرض الأسعار المصادمة والمفاتيح

فيديو

Webhooks في العمل

شاهد كيف تعمل Webhooks من PaperOffice في الممارسة العملية — في الفيديو.

أسئلة

الأسئلة الشائعة حول Webhooks

كيف أتحقق من التسليم؟

احسب HMAC-SHA256 على نص الطلب الخام باستخدام سر اشتراكك وقارن النتيجة في وقت تشغيل ثابت مع رأس X-PaperOffice-Signature (تنسيق sha256=<hex>). إذا لم تتطابق التوقيع، فأجب بـ HTTP 401 ولا تعالج النص.

من أين يأتي السر؟

عند إنشاء الاشتراك عبر POST /latest/webhooks/subscribe. اترك حقل السر فارغًا، وسيقوم PaperOffice بتوليد سر وإرجاعه مرة واحدة في الاستجابة. يمكنك استبداله في أي وقت عبر POST /latest/webhooks/update.

ماذا يحدث إذا لم يستجيب نقطة النهاية الخاصة بي؟

تُعتبر أي استجابة خارج نطاق HTTP 2xx أو انتهاء المهلة (Timeout) محاولة فاشلة. تقوم PaperOffice بإعادة المحاولة وفقاً لسياسة إعادة المحاولة (أسي، خطي، لا شيء) حتى يصل عدد المحاولات إلى العدد المحدد (0-10، والافتراضي هو 5). يتم تسجيل كل محاولة مع رمز الحالة والاستجابة وقياس الوقت في سجل التسليم.

هل يمكن أن تصل نفس التسليم مرتين؟

نعم، قد يحدث ذلك عند إعادة المحاولة بعد انتهاء المهلة. لذا، يرجى إجراء إزالة التكرار (Deduplication) باستخدام X-PaperOffice-Event-ID: تكون المعرّف فريداً لكل حدث ومناسباً كمفتاح للتحكم في التكرار (Idempotency Key) في قاعدة بياناتك.

ما هي الأحداث التي يمكنني الاشتراك فيها؟

22 نوعاً من الأحداث من أربع مجموعات: المستندات، والمهام، ومساحات العمل، والمهام (Tasks). يمكنك الاشتراك في أحداث فردية أو استخدام الرمز البردي * للاشتراك في الكل. يمكنك تضييق نطاق الاشتراك باستخدام عوامل التصفية (مثل workspace_id أو pofid).

في أي خطة تتضمن Webhooks؟

تتوفر Webhooks بدءاً من خطة Professional. يعرض جدول الأسعار الخطة المناسبة لإعدادك.

التشغيل والثقة

ما تتحقق منه فرق المؤسسات قبل المكالمة الأولى

العقود، والأمان، والدعم، والحدود، كل الروابط في مكان واحد.

المحطة التالية

كيف تستمر

الخطوة التالية الموصى بها في قمع المطورين وفرعان مناسبان.

Postman Collectionاستيراد، اختبار، وتصحيح في Postman Publishable Keysمفاتيح آمنة للمتصفح لـ AI Artifacts وتطبيقات الواجهة الأمامية أول استدعاء APIاحصل على المفتاح، أرسل الطلب، تحقق من الاستجابة

العودة إلى بداية المطور

افهموا PaperOffice AI في 14 دقيقة.

كيف ترغبون في استخدام PaperOffice؟

أحداث في الوقت الفعلي. تم التسليم بتوقيع HMAC.

22 نوع من الأحداث، مجمعة حسب الكيان

المستندات

المهام

Workspaces

المهام

يتبع كل تسليم نفس المخطط

قم بالتحقق من كل تسليم باستخدام HMAC-SHA256

ثلاث استراتيجيات إعادة محاولة، حتى 10 تكرارات

أسي (افتراضي)

خطي

بدون

خمسة نقاط نهاية تحت /latest/webhooks/

مصمم من الأساس ليكون آمنًا

يمكن تكوين سلوك التسليم لكل اشتراك

Webhooks في العمل

الأسئلة الشائعة حول Webhooks

ما تتحقق منه فرق المؤسسات قبل المكالمة الأولى

كيف تستمر