مرجع API · إشعارات Webhook
تسجيل عنوان الإشعارات
PUT
/v1/webhook-endpointسجّل عنوان HTTPS لتطبيقك وأكمل تحدّي التحقق قبل استقبال النتائج.
الصلاحيةلا شيء
المصادقةتغيير موقَّع
ردّ أنيسموقَّع
حدود الموظفين التي يُحتسب ضمنهاكل الاستدعاءات
حزمة SDK لـ .NET
anis.WebhookEndpoint.SetAsync(request)- وقّع بصمة المحتوى برقم استخدام واحد جديد، دون
Idempotency-Key. لا ينشئ هذا التغيير عملية شراء.
الاستدعاء
موقَّع بمفتاحك، مع رقم استخدام لمرة واحدة (nonce) وبصمة للمحتوى.
الترويسات: Signature-Input، Signature، Content-Digest، Nonce، X-Anis-Date، Accept-Language (اختياري). تضبطها حزم SDK كلها نيابةً عنك.
المحتوى: SetWebhookEndpointRequest، بصيغة JSON.
| الحقل | النوع | ملاحظات |
|---|---|---|
urlإلزامي | string | استخدم HTTPS على المنفذ 443 واسم مضيف عام يحتوي على نقطة، بلا معلومات مستخدم أو جزء fragment، وبحد أقصى 2048 حرفًا. |
الردود
| الحالة | المعنى | المحتوى |
|---|---|---|
| 200 | نجاح. | WebhookEndpoint |
| 400 | مرفوض: الاستدعاء الموقّع غير سليم البنية. | مشكلة |
| 401 | مرفوض: لم تتم المصادقة. | مشكلة |
| 403 | مرفوض: غير مسموح. | مشكلة |
| 404 | مرفوض: غير موجود، أو ليس لك. | مشكلة |
| 409 | مرفوض: يتعارض مع الحالة الحالية. | مشكلة |
| 422 | مرفوض: الاستدعاء يخالف قاعدة. | مشكلة |
| 429 | مرفوض: بلغتَ حدًا. | مشكلة |
| 503 | لا قرار: خدمة مطلوبة غير متاحة. | مشكلة |
كل ردّ على هذا الاستدعاء موقَّع من أنيس — النجاح وكل رفض. اشترط وجود التوقيع وتحقّق منه قبل أن تتصرف بناءً على الردّ؛ والردّ بلا توقيع فشل، لا يُعدّ ردًّا (كيف).
حالات الرفض
كل رفض لهذا الاستدعاء مشكلةٌ موقَّعة. ابنِ منطقك على رمزها code؛ وكلٌّ منها يرتبط بصفحة تشرح معناه وما عليك فعله.
| الخطأ | الرمز | الحالة |
|---|---|---|
| بيانات اعتماد غير صالحة | invalid_credentials | 401 |
| استدعاء موقّع غير سليم البنية | malformed_signed_request | 400 |
| صلاحية غير كافية | insufficient_scope | 403 |
| عنوان المصدر غير مسموح | source_ip_not_allowed | 403 |
| تجاوزت حدّ الاستدعاءات | rate_limited | 429 |
| فشل التحقق | validation_failed | 422 |
| الخدمة غير متاحة | dependency_unavailable | 503 |
| انتهت مهلة الاستدعاء | request_timeout | 504 |
| خطأ داخلي | internal_error | 500 |
| اكتُشف تكرار | replay_detected | 409 |
| غير موجود | resource_not_found | 404 |
| عنوان الإشعارات مرفوض | webhook_endpoint_invalid | 422 |
الأنواع
SetWebhookEndpointRequest
| الحقل | النوع | ملاحظات |
|---|---|---|
urlإلزامي | string | استخدم HTTPS على المنفذ 443 واسم مضيف عام يحتوي على نقطة، بلا معلومات مستخدم أو جزء fragment، وبحد أقصى 2048 حرفًا. |
WebhookEndpoint
| الحقل | النوع | ملاحظات |
|---|---|---|
urlموجود دائمًا | string | عنوان HTTPS المسجّل لتطبيقك؛ ويكون null إن لم يُسجّل عنوان. |
statusموجود دائمًا | WebhookEndpointStatus | تكون notConfigured أو pendingVerification أو verified أو disabled. لا يستقبل العنوان المعطّل أي إشعارات. |
generationموجود دائمًا | integer | رقم جيل التسجيل الوارد في تحدّي التحقق؛ ويكون null إن لم يُسجّل عنوان. |