تخطَّ إلى المحتوى

Webhooks

عند تكوين عنوان URL ل webhook، يتم إخطار الخادم الخاص بك عند انتهاء مهمة ترجمة الملف (/jobs) (سواء نجحت أم لا). أما المهام التي يتم إلغاؤها باستخدام POST /jobs/{id}/cancel فلا تُرسل أي استدعاء خلفي. بالنسبة لعمليات المستندات ومهام الوسائط، يجب الاستعلام عبر نقاط نهاية الاستعلام الخاصة بها.

يتم إدارتها عبر واجهة برمجة التطبيقات، بحد أقصى 3 لكل مستخدم:

POST /api/v1/webhooks create
GET /api/v1/webhooks list
PATCH /api/v1/webhooks/{id} update / disable
DELETE /api/v1/webhooks/{id} delete

إنشاء مثال:

Terminal window
curl -X POST https://omnidoc.top/api/v1/webhooks \
-H "X-API-Key: sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/hooks/omnidoc",
"secret": "your-signing-secret",
"events": ["job.completed"],
"description": "Production callback"
}'

يجب أن يكون عنوان URL قابلًا للوصول من الإنترنت العام، ويفضل عبر HTTPS؛ أما الشبكات الخاصة والعناوين المحلية وعناوين URL غير الصحيحة فتُرجع 400. يمكن لطلب PATCH تعديل url وsecret وevents وdescription وstatus (active / disabled).

تنسيق الاستدعاء العكسي

Section titled “تنسيق الاستدعاء العكسي”
POST your-webhook-url
Content-Type: application/json
X-Webhook-Event: job.completed
X-Webhook-Timestamp: 1782900150
X-Webhook-Signature: sha256=...
{
"event": "job.completed",
"timestamp": 1782900150,
"data": {
"job_id": "q3f8s6c2a9m1k4tx",
"status": "completed",
"file_name": "report.docx",
"char_count": 12840
}
}
الحدثعندما
job.completedتنتهي الوظيفة؛ data.status هو completed أو failed

تستخدم الوظائف الفاشلة أيضًا الحدث job.completed؛ ويمكن التمييز بينها باستخدام data.status == "failed" والحدث الاختياري data.error. أما الوظائف الناجحة فلا تحتوي على حقل error. يمثل data.char_count عدد الأحرف في الترجمة، بينما يمثل 0 ذلك للوظائف الفاشلة.

events يقبل فقط job.completed و* (جميع الأحداث)؛ أما القيم الأخرى أو القائمة الفارغة فتُرجع الرمز 422. في طلب PATCH، اترك الحقول التي لا ترغب في تغييرها؛ كما أن إرسال null يُرجع أيضًا الرمز 422.

عندما تُحدِّد secret على webhook، يحمل كل استدعاء خلفي X-Webhook-Signature. تحقق من ذلك باستخدام HMAC-SHA256 عبر نص الجسم الخام للطلب :

import hashlib
import hmac
import json
import time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict:
if not verify_webhook(payload, signature, secret):
raise ValueError("invalid signature")
event = json.loads(payload)
if abs(time.time() - event["timestamp"]) > tolerance:
raise ValueError("stale event")
return event

تغطي التوقيعة الجسم فقط، وليس الرؤوس. لحماية إعادة التشغيل، تحقق من timestamp في الجسم بعد نجاح التوقيعة (وهو يساوي X-Webhook-Timestamp، لكن قيمة الجسم فقط هي التي يتم توقيعها)، وقم بإزالة التكرارات باستخدام data.job_id وdata.status. تعيد عمليات المحاولة إرسال جسم أول عملية تسليم دون تغيير، مع نفس timestamp، وتتم آخر محاولة بعد حوالي 8.6 ساعات من أول عملية تسليم، لذا لا تجعل النافذة أقصر من ذلك (المثال يستخدم 12 ساعة).

  • يجب على المستلم إرجاع 2xx خلال 15 ثانية لاعتبار عملية التسليم ناجحة؛ ولا يتم اتباع عمليات إعادة التوجيه.
  • يتم إعادة محاولات التسليم الفاشلة (بسبب انتهاء المهلة أو خطأ الاتصال أو غير 2xx) تلقائيًا: بعد دقيقة واحدة، و5 دقائق، و30 دقيقة، وساعتين، و6 ساعات من الفشل السابق، بحد أقصى 6 محاولات تسليم لكل حدث، ثم تتوقف المحاولات.
  • تُعاد المحاولات إلى عنوان URL الحالي للويب هوك مع عدم تغيير النص الأساسي (timestamp وdata والتوقيع يتطابقان مع التسليم الأول؛ وإذا تغير secret في هذه الأثناء، فإن secret الجديد هو الذي يُستخدم للتوقيع)؛ ولا يتم إرسال الأحداث التي سبق تسليمها مرة أخرى.
  • عندما يتم تعطيل webhook أو حذفه أو إلغاء اشتراكه في الحدث، يتم إلغاء عمليات إعادة المحاولة المعلقة الخاصة به.
  • يجب أن يتعامل المستقبلون مع الأحداث بشكل مطابق لحالتها الأصلية وفقًا للمحددات data.job_id وdata.status، وأن يستجيبوا بسرعة بعد حفظها بأمان.
  • يتم تسليم العديد من محددات الويب الخاصة بحساب واحد بشكل متوازٍ؛ ولا يؤدي بطء أحد المستقبلين إلى إبطاء الآخرين
  • بعد 10 عمليات تسليم فاشلة متتالية (بما في ذلك المحاولات إعادة)، يتم تعطيل webhook تلقائيًا؛ قم بإعادة تمكينه باستخدام PATCH بمجرد إصلاح المستلم.
  • يعرض GET /api/v1/webhooks وقت التشغيل الأخير لكل webhook، ورمز الحالة، وعدد حالات الفشل المتتالية