إنشاء خطاف ويب

POST /v1/webhooks

تسجيل عنوان URL لخطاف ويب لتلقي طلبات POST عند حدوث أحداث الاستخراج. يمكن لكل مستخدم أن يمتلك حتى 10 خطافات ويب نشطة.

جرّبه

اختبر هذا الـ endpoint بشكل تفاعلي في Swagger UI.

المصادقة مطلوبة

أدرج مفتاح API في ترويسة Authorization.

الطلب

الترويسات

الترويسة	القيمة	مطلوب
Authorization	Bearer <token>	نعم
Content-Type	application/json	نعم

الجسم

الحقل	النوع	مطلوب	الوصف
url	string	نعم	نقطة نهاية HTTPS التي ستتلقى طلبات POST لخطاف الويب.
events	string[]	نعم	الأحداث المراد الاشتراك فيها. واحد على الأقل مطلوب. القيم: "extraction.completed" و"extraction.failed".

أمثلة الكود

curl

curl -X POST https://api.docmap.io/v1/webhooks \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/docmap",
    "events": ["extraction.completed", "extraction.failed"]
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/docmap',
    events: ['extraction.completed', 'extraction.failed'],
  }),
})

const { data } = await response.json()

// IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
console.log('Signing Secret:', data.secret)
console.log('Webhook ID:', data.webhook.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.post(
    "https://api.docmap.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://your-app.com/webhooks/docmap",
        "events": ["extraction.completed", "extraction.failed"],
    },
)

data = response.json()["data"]

# IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
print(f"Signing Secret: {data['secret']}")
print(f"Webhook ID: {data['webhook']['id']}")

الاستجابة

الحالة: 200 OK

جسم الاستجابة مغلف في كائن data.

WARNING

سر التوقيع يُرجع فقط في هذه الاستجابة. خزّنه بشكل آمن فوراً -- لا يمكن استرجاعه لاحقاً. تحتاجه للتحقق من توقيعات خطافات الويب.

الحقول

الحقل	النوع	الوصف
secret	string	سر توقيع HMAC-SHA256 (64 حرف سداسي عشري). يُعرض مرة واحدة فقط.
webhook	object	كائن البيانات الوصفية لخطاف الويب (انظر أدناه).

كائن webhook:

الحقل	النوع	الوصف
id	string	معرّف فريد لخطاف الويب.
userId	string	معرّف المستخدم الذي يملك خطاف الويب.
url	string	عنوان URL لنقطة النهاية المسجلة.
events	string[]	الأحداث التي اشترك فيها خطاف الويب.
active	boolean	ما إذا كان خطاف الويب نشطاً. دائماً true لخطاف ويب مُنشأ حديثاً.
createdAt	string	طابع زمني ISO 8601 لوقت إنشاء خطاف الويب.

مثال

{
  "data": {
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "webhook": {
      "id": "webhook-abc123def456",
      "userId": "uid_a1b2c3d4e5f6",
      "url": "https://your-app.com/webhooks/docmap",
      "events": ["extraction.completed", "extraction.failed"],
      "active": true,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  }
}

الأخطاء

الحالة	الرمز	الوصف
400	MAX_WEBHOOKS_REACHED	لقد وصلت إلى الحد الأقصى وهو 10 خطافات ويب نشطة. احذف خطاف ويب موجوداً قبل إنشاء واحد جديد.
401	UNAUTHORIZED	مفتاح API / رمز مفقود أو غير صالح أو منتهي الصلاحية.