POST/v1/webhooks

إنشاء Webhook

يسجّل رابطاً ويشترك فيه بنوع أو أكثر من الأحداث.

الصلاحية المطلوبة: webhooks.manageحد الطلبات: 10 rps

سر التوقيع يُعاد مرة واحدة فقط، ضمن استجابة هذا الطلب — احفظه فوراً. يحتفظ سما برايم بنسخة مشفّرة فقط.

المعطيات

urlstringمطلوب

رابط تسليم بصيغة https.

eventsstring[]مطلوب

مصفوفة بأنواع الأحداث المشترك فيها — انظر مرجع الأحداث.

أمثلة الكود

curl -X POST "https://samaprime.com/api/v1/webhooks" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example/callbacks/salamcash","events":["order.completed"]}'

الاستجابة

→ 201
{
  "data": {
    "id": "cm_wh_01J8Z9A1BBCCDD",
    "url": "https://merchant.example/webhooks/samaprime",
    "events": [
      "order.completed",
      "order.failed"
    ],
    "secret": "whsec_3f9a2b7c1e0d4a6f8b5c2d1e9f0a7b3c",
    "active": true
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

الأخطاء

الحالة	الرمز
400	`validation_failed` يجب أن يكون النص بالشكل { url: string, events: string[] }.
400	`invalid_event_type` نوع حدث أو أكثر غير معروف — انظر مرجع الأحداث.
400	`insecure_url` يجب أن يكون الرابط https:// (يُسمح بـ http:// على loopback فقط للاختبار المحلي).