Webhook Documentation

وب‌هوک‌ها

وب‌هوک‌ها به شما امکان می‌دهند نتیجه پردازش فایل، وضعیت job، خطاها و رخدادهای مهم را به‌صورت خودکار و بلادرنگ در سرور خود دریافت کنید. به‌جای polling مداوم، سیستم ما پس از تکمیل رویداد، یک درخواست HTTP به آدرس تعیین‌شده شما ارسال می‌کند.

Sample Webhook URL
https://yourdomain.com/webhooks/filekit
Method
POST
Content-Type
application/json
Authentication
X-FileKit-Signature / Secret
Retries
Automatic retry on non-2xx

رویدادهای پشتیبانی‌شده

EventDescriptionWhen Fired
job_createdایجاد job جدید برای پردازش فایلبلافاصله پس از ثبت درخواست
job_processingشروع پردازش فایلزمانی که پردازش آغاز شود
conversion_completedتبدیل فایل با موفقیت کامل شدپس از تولید فایل خروجی
conversion_failedتبدیل فایل با خطا مواجه شددر صورت failure در پردازش

هدرهای ارسالی

HeaderRequiredDescriptionExample
Content-TypeYesنوع داده ارسالیapplication/json
X-FileKit-EventYesنام رویدادconversion_completed
X-FileKit-DeliveryYesشناسه یکتای تحویل برای idempotencyevt_01HZX2ABCD9PQ
X-FileKit-TimestampYestimestamp ارسال برای جلوگیری از replay1735689600
X-FileKit-SignatureRecommendedامضای payload با secret اشتراکیsha256=abcdef123456...

اعتبارسنجی امضای وب‌هوک

مراحل اعتبارسنجی
1. Raw request body را بدون تغییر دریافت کنید.
2. مقدار X-FileKit-Timestamp را بخوانید.
3. مقدار X-FileKit-Signature را بخوانید.
4. رشته زیر را بسازید:
   timestamp + "." + rawBody
5. با secret خود، HMAC-SHA256 تولید کنید.
6. خروجی را با signature دریافتی مقایسه کنید.
7. اگر timestamp خیلی قدیمی بود، درخواست را رد کنید.
8. اگر delivery id تکراری بود، دوباره پردازش نکنید.
Node.js Verification Example
const crypto = require("crypto");

function verifyWebhook(rawBody, timestamp, signature, secret) {
  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}
Python Verification Example
import hmac
import hashlib

def verify_webhook(raw_body, timestamp, signature, secret):
    signed_payload = f"{timestamp}.{raw_body}"
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        signed_payload.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

ساختار وب‌هوک موفق

{
  "event": "conversion_completed",
  "delivery_id": "evt_01HZX2ABCD9PQ",
  "created_at": "2026-06-01T10:30:00Z",
  "data": {
    "job_id": "job_123456",
    "status": "completed",
    "input_file_name": "input.txt",
    "output_file_name": "output.pdf",
    "output_format": "pdf",
    "file_url": "https://filekit.ir/files/output.pdf",
    "size": 24576,
    "mime_type": "application/pdf"
  }
}

ساختار وب‌هوک خطا

{
  "event": "conversion_failed",
  "delivery_id": "evt_01HZX2XYZ789",
  "created_at": "2026-06-01T10:35:00Z",
  "data": {
    "job_id": "job_123456",
    "status": "failed",
    "error": {
      "code": "UNSUPPORTED_FORMAT",
      "message": "The requested output format is not supported for this file."
    }
  }
}

نمونه ارسال مجدد (Retry / Redelivery)

{
  "event": "conversion_completed",
  "delivery_id": "evt_01HZX2ABCD9PQ",
  "attempt": 2,
  "redelivered": true,
  "created_at": "2026-06-01T10:30:00Z",
  "data": {
    "job_id": "job_123456",
    "status": "completed",
    "file_url": "https://filekit.ir/files/output.pdf"
  }
}

Best Practices

توصیه‌های مهم برای پیاده‌سازی وب‌هوک
  • همیشه signature را با secret اعتبارسنجی کنید.
  • برای جلوگیری از replay attack، timestamp را بررسی کنید.
  • delivery_id را ذخیره کنید تا رویدادهای تکراری دوباره پردازش نشوند.
  • در سریع‌ترین زمان ممکن پاسخ 2xx برگردانید و پردازش سنگین را async انجام دهید.
  • raw request body را برای validation بدون تغییر نگه دارید.
  • روی endpoint وب‌هوک rate limiting و logging مناسب داشته باشید.
  • در صورت failure موقت، پاسخ 5xx بدهید تا retry انجام شود.

خروجی Mock Webhook

هنوز payloadی تولید نشده است.