דלג לתוכן
סקירה סקירה חדשות חדשות
שיתוף

Webhooks ואירועים

אירועים בזמן אמת. מסירות חתומות HMAC.

PaperOffice מתקשר לקצה שלך ברגע שדוקומנט, משימה, Workspace או משימה משתנים. ללא Polling.

22 סוגי אירועים, חתימת HMAC-SHA256, שלוש אסטרטגיות ניסיון חוזר ויומן מסירה לכל ניסיון.

HMAC-SHA256 בכל מסירה עד 10 חזרות (סטנדרט 5) איידמפוטנטי לפי מזהה אירוע

אירועים זמינים

22 סוגי אירועים, מקובצים לפי ישות

הירשמו לאירועים בודדים או השתמשו במחליף * עבור הכל.

מסמכים

14
  • document.uploaded העלאת מסמך חדש ל-Workspace
  • document.created כינוי ל-document.uploaded (תאימות)
  • document.processed צינור OCR/AI-IDP הושלם בהצלחה
  • document.edited מסמך ערוך: עודכנו מטא-נתונים, תגיות או תוכן
  • document.deleted מסמך הועבר לסל המיחזור
  • document.restored מסמך שוחזר מסל המיחזור
  • document.moved העברת מסמך בין Workspaces
  • document.version_created גרסה חדשה של מסמך קיים
  • document.lifecycle_changed סטטוס שמירה/ארכיון השתנה
  • document.comment_added הערה למסמך נוצרה
  • document.note_added העצה פנימית צורפה
  • document.tag_added תג הוקצה למסמך
  • document.legal_hold_placed החזקת משפט מופעלת (בלתי ניתנת לשינוי)
  • document.legal_hold_released החזקת משפט בוטלה

משימות

3
  • job.completed משימה אסינכרונית הושלמה בהצלחה
  • job.failed משימה אסינכרונית נכשלה סופית
  • job.progress עדכון התקדמות בעבודות ארוכות

Workspaces

2
  • workspace.shared מרחב עבודה משותף למשתמש או לצוות
  • workspace.unshared גישה למרחב העבודה בוטלה

משימות

3
  • 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 של הגוף הגולמי, מקודדת ב-HEX
cURL
curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "My Production Webhook",    "url": "https://yourdomain.com/webhooks/paperoffice",    "events": ["document.processed", "job.completed", "job.failed"],    "retry_policy": "exponential",    "max_retries": 5,    "timeout_ms": 10000  }'

אימות חתימה

אמת כל מסירה באמצעות 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 ייצור אותו ויחזיר אותו פעם אחת בלבד.

ניסיונות חוזרים ואספקה

שלוש אסטרטגיות ניסיון חוזר, עד 10 חזרות

בחר את המדיניות לכל הרשמה. כל ניסיון יתועד עם קוד סטטוס, גוף התגובה וזמן מדידה.

  • ברירת מחדל exponential

    אקספוננציאלי (ברירת מחדל)

    המרווח בין ניסיונות ההתקשרות מוכפל לאחר כל כישלון.

  • linear

    ליניארי

    המרווח בין ניסיונות ההתקשרות גדל בצעד קבוע.

  • none

    ללא

    ללא חזרה, גם לא במקרה של שגיאות 5xx (שליחה ושכחה). שימושי עבור הוקים לבדיקות.

  • הצלחה HTTP 2xx בתוך חלון זמן ההמתנה
  • מקסימום ניסיונות חזרה עד 10 ניסיונות חזרה (ברירת מחדל: 5)
  • התנתקות זמן 1.000–30.000 מ"ש למאמץ (ברירת מחדל 10.000)
  • יומן מסירה כל מאמץ נרשם; הפרוטוקול נשמר גם לאחר מחיקת המנוי.

ניהול-API

חמישה נקודות קצה תחת /latest/webhooks/

יצירה, רשימה, עדכון ומחיקה של מנויים — כולל נקודת קצה לבדיקה. כל קריאה כוללת אסימון Bearer.

  • POST /webhooks/subscribe יצירת מנוי; הפעלות חתומות באמצעות HMAC-SHA256 כלי MCPpo-webhooks-subscribe
  • GET /webhooks/list רשימת כל מנועי Webhook של החשבון כלי MCPpo-webhooks-list
  • POST /webhooks/update עדכון כתובת URL, אירועים, כותרות, מדיניות ניסיונות חוזרים או סטטוס פעיל כלי MCPpo-webhooks-update
  • POST /webhooks/delete מחיקת מנוי; פרוטוקול המשלוח נשמר כלי MCPpo-webhooks-delete
  • POST /webhooks/test שליחת אירוע בדיקה למנוי ובדיקת משלוח כלי MCPpo-webhooks-test

אבטחה

מותאם אבטחה מהיסוד

שישה מנגנונים הפועלים בכל משלוח — מצד PaperOffice ומצדך.

  • HMAC-SHA256

    כל משלוח נחתם עם ה-Secret שלך. ההשוואה חייבת להתבצע בזמן קבוע.

  • הגנת SSRF

    כתובות IP פרטיות ופנימיות, Localhost ונקודות קצה של מטא-נתונים בענן חסומות במהלך ההרשמה וההעברה.

  • בטוח מפני DNS Rebinding

    כתובת ה-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 stehen בתוכנית Professional ואילך. איזו תוכנה מתאימה להגדרה שלך, ניתן לראות בסקירת המחירים.

וידאו

Webhooks בפעולה

צפה כיצד PaperOffice Webhooks פועל במציאות — בסרטון.

Webhooks בפעולה

שאלות

שאלות נפוצות לגבי Webhooks

כיצד לאמת מסירה?

חשב HMAC-SHA256 על גוף הבקשה הגולמי באמצעות הסוד של המנוי שלך והשווה את התוצאה בזמן קבוע עם הכותרת X-PaperOffice-Signature (פורמט sha256=<hex>). אם החתימה אינה תואמת, החזר HTTP 401 ועבד את הגוף.

מאיפה מגיע הסוד?

בעת יצירת המנוי באמצעות POST /latest/webhooks/subscribe. השאר את השדה secret ריק, PaperOffice ייצור סוד ויחזיר אותו פעם אחת בתגובה. באמצעות POST /latest/webhooks/update ניתן להחליפו בכל עת.

מה קורה אם הנקודה הסופית שלי לא מגיבה?

כל תגובה שאינה HTTP 2xx או הפסקת חיבור נחשבת לכישלון. בהתאם למדיניות החזרה (מעריכית, ליניארית, ללא), PaperOffice תחזור על המשלוח עד למספר החזרות שנקבע (0–10, ברירת מחדל 5). כל ניסיון מופיע ביומן המשלוח עם קוד הסטטוס, התגובה ומדידת הזמן.

האם אותו משלוח יכול להגיע פעמיים?

כן, זה אפשרי במקרה של חזרות לאחר הפסקת חיבור. לכן, בצע השמטת כפילויות באמצעות X-PaperOffice-Event-ID: המזהה ייחודי לכל אירוע ומתאים כמפתח אימפוטנציה במסד הנתונים שלך.

אילו אירועים ניתן להירשם אליהם?

22 סוגי אירועים מארבע קבוצות: מסמכים, משימות, חלונות עבודה ופעולות. ניתן להירשם לאירועים בודדים או לכולם באמצעות המקום החופשי *. באמצעות פילטרים (כגון workspace_id או pofid) ניתן להגביל הרשמה נוספת.

באיזה תוכנית כלולים Webhooks?

Webhooks זמינים החל מהתוכנית Professional. התוכנה המתאימה להגדרות שלך מוצגת בסקירת המחירים.

היכן תרצו לנסות את PaperOffice?

המחשב והסמארטפון מחוברים: מרחב עבודה במחשב, תפיסה בטלפון.

גרסת הניסיון מוכנה

מאיפה ברצונכם להתחיל?

המרחב העבודה המלא מותאם למחשב. הגרסה לנייד מתאימה לתפיסה, בדיקה ואישור מסמכים.

app.paperoffice.ai

להתחיל במחשב

קישור הכניסה האישי יישלח לכתובת הדוא"ל שצוינה.

להירשם בחינם פתיחת היישום יישום PaperOffice המוצר המלא: ווב, שולחן עבודה ונייד. לכידה, ארגון, חיפוש ועבודה על מסמכים עם הצוות. נדרש חשבון חינם פתיחת Playground Playground נסו פונקציות נבחרות מיד — ללא רישום, עם מפתח API להדגמה מוגבל. ללא הרשמה, אך עם מפתח API להדגמה מוגבל