Webhooks

تتيح لك webhooks استقبال إشعارات أحداث فورية من PDFSimple في تطبيقك. بدلاً من استعلام واجهة برمجة التطبيقات باستمرار عن حالة المهمة، سجّل نقطة نهاية وسيرسل PDFSimple طلب POST موقّعًا إليها عند حدوث حدث.

إعداد webhook

1. اذهب إلى لوحة التحكم ← Webhooks وانقر على إضافة نقطة نهاية.
2. أدخل رابط نقطة نهاية HTTPS الخاصة بك (مثل، https://yourapp.com/webhooks/pdfsimple).
3. اختر الأحداث التي تريد استقبالها (مثل، job.completed وjob.failed).
4. انقر على إنشاء. سيُعرض مفتاح سري فريد لـ webhook — انسخه فورًا، فهو يُعرض مرة واحدة فقط.
5. خزّن المفتاح السري بأمان في متغيرات بيئة تطبيقك.

أحداث Webhook

• job.completed — اكتملت مهمة معالجة PDF بنجاح. تتضمن الحمولة معرّف المهمة ورابط ملف الإخراج والبيانات الوصفية.
• job.failed — واجهت المهمة خطأً. تتضمن الحمولة رسالة الخطأ.

التحقق من توقيعات Webhook

يتضمن كل طلب webhook رأس X-PDFSimple-Signature يحتوي على توقيع HMAC-SHA256 لنص الطلب الخام، محسوبًا باستخدام مفتاح webhook السري الخاص بك. تحقق دائمًا من هذا التوقيع قبل معالجة الحمولة.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

إعادة المحاولات وضمانات التسليم

إذا لم تُرجِع نقطة النهاية الخاصة بك استجابة 2xx خلال 30 ثانية، سيعيد PDFSimple محاولة التسليم بتأخير تصاعدي، حتى 5 محاولات على مدى 30 يومًا. يُحتفظ بأحداث webhook لمدة 30 يومًا.