# الويب هوك استقبل الأحداث (رسائل جديدة، تحديثات التسليم) على خادمك مباشرة. ## عرض أنواع الأحداث ``` GET https://api.saei.automize.sa/v1/event_types ``` كل الأحداث التي يمكنك الاشتراك فيها. - الصلاحية: webhooks:read - يعمل في وضع الاختبار ### الاستجابة 200 أنواع الأحداث. ```json { "object": "list", "data": [ { "object": "event_type", "type": "message.delivered", "object_type": "string", "description": "string" } ], "has_more": false, "next_cursor": "string" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ## إعادة الإرسال الآن ``` POST https://api.saei.automize.sa/v1/webhook_deliveries/{id}/retry ``` يرسل نفس الحدث مرة أخرى (نفس `webhook-id` وتوقيع جديد)، مثلًا بعد إصلاح خادمك. - الصلاحية: webhooks:write - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. ### الاستجابة 202 أُضيف لقائمة الإرسال. ```json { "id": "del_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_delivery", "livemode": false, "webhook_endpoint_id": "string", "event_id": "string", "event_type": "string", "status": "pending", "attempts": 0, "http_status": 0, "duration_ms": 0, "response_snippet": "string", "last_error": "string", "next_attempt_at": "2026-10-01T09:30:00Z", "delivered_at": "2026-10-01T09:30:00Z", "created_at": "2026-10-01T09:30:00Z", "payload": { "id": "evt_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "event", "type": "message.delivered", "version": "2", "created_at": "2026-10-01T09:30:00Z", "livemode": false, "workspace_id": "ws_12", "data": { "object": {}, "previous_attributes": {} } } } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing` ## عرض نقاط استقبال الويب هوك ``` GET https://api.saei.automize.sa/v1/webhook_endpoints ``` النقاط التابعة لوضع المفتاح (مفاتيح التشغيل ترى النقاط الحية، ومفاتيح الاختبار ترى نقاط الاختبار). - الصلاحية: webhooks:read - يعمل في وضع الاختبار ### الاستجابة 200 نقاط الاستقبال. ```json { "object": "list", "data": [ { "id": "we_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_endpoint", "livemode": false, "url": "string", "description": "string", "enabled_events": [ "string" ], "status": "enabled", "disabled_reason": "string", "secret_preview": "string", "secret": "string", "created_at": "2026-10-01T09:30:00Z", "updated_at": "2026-10-01T09:30:00Z" } ], "has_more": false, "next_cursor": "string" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 403 المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع. ```json { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.", "required_scope": "messages:send", "doc_url": "https://app.example.com/docs/errors#insufficient_scope", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `rate_limited` ## إضافة نقطة استقبال ويب هوك ``` POST https://api.saei.automize.sa/v1/webhook_endpoints ``` سنرسل كل حدث مشترك فيه إلى `url` بطلب POST بصيغة JSON، موقّعًا بمعيار [Standard Webhooks](https://www.standardwebhooks.com). تتضمن الاستجابة سر التوقيع `secret` **مرة واحدة فقط**: احفظه للتحقق من التواقيع. في بيئة التشغيل يجب أن يبدأ الرابط بـ `https://` وأن يكون متاحًا للعموم. حتى 10 نقاط لكل مساحة عمل. يحمل الحدث البيانات نفسها التي تُرجعها نقطة القراءة الخاصة به، لذلك تحتاج كل عائلة أحداث صلاحية القراءة نفسها: `message.*` تحتاج `messages:read`، و`contact.*` تحتاج `contacts:read`، و`conversation.*` تحتاج `conversations:read`، و`campaign.*` تحتاج `campaigns:read`، و`flow.*` تحتاج `flows:read`، و`template.*` تحتاج `templates:read`. أما `["*"]` فتحتاجها كلها. ويسري الفحص نفسه عند تغيير رابط نقطة الاستقبال أو أحداثها. - الصلاحية: webhooks:write - يعمل في وضع الاختبار - يقبل Idempotency-Key ### المعاملات - `Idempotency-Key` (header): أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة. ### الطلب ```json { "url": "https://example.com/webhooks/whatsapp", "enabled_events": [ "message.received", "message.delivered", "message.read", "message.failed" ], "description": "Order system" } ``` ### الاستجابة 201 تم الإنشاء. يظهر `secret` الآن فقط. ```json { "id": "we_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_endpoint", "livemode": true, "url": "https://example.com/webhooks/whatsapp", "description": "Order system", "enabled_events": [ "message.received", "message.delivered", "message.read", "message.failed" ], "status": "enabled", "disabled_reason": null, "secret_preview": "whsec_…K3x=", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw/kNEBw0UXK3x=", "created_at": "2026-10-01T09:30:00Z", "updated_at": "2026-10-01T09:30:00Z" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 403 المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع. ```json { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.", "required_scope": "messages:send", "doc_url": "https://app.example.com/docs/errors#insufficient_scope", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 422 الطلب غير صالح. يوضّح `details` كل حقل به خطأ. ```json { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "The to field is required.", "param": "to", "details": [ { "param": "to", "code": "parameter_missing", "message": "The to field is required." } ], "doc_url": "https://app.example.com/docs/errors#parameter_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `parameter_missing`, `parameter_invalid`, `webhook_url_invalid`, `webhook_endpoint_limit`, `insufficient_scope`, `rate_limited` ## جلب نقطة استقبال ``` GET https://api.saei.automize.sa/v1/webhook_endpoints/{id} ``` - الصلاحية: webhooks:read - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. ### الاستجابة 200 نقطة الاستقبال. ```json { "id": "we_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_endpoint", "livemode": false, "url": "string", "description": "string", "enabled_events": [ "string" ], "status": "enabled", "disabled_reason": "string", "secret_preview": "string", "secret": "string", "created_at": "2026-10-01T09:30:00Z", "updated_at": "2026-10-01T09:30:00Z" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing` ## تعديل نقطة استقبال ``` PATCH https://api.saei.automize.sa/v1/webhook_endpoints/{id} ``` غيّر الرابط أو الأحداث، أو أوقفها مؤقتًا بـ `"disabled": true`. إعادة التفعيل تصفّر عدّاد الإخفاقات. - الصلاحية: webhooks:write - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. ### الطلب ```json { "enabled_events": [ "*" ] } ``` ### الاستجابة 200 نقطة الاستقبال بعد التعديل. ```json { "id": "we_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_endpoint", "livemode": false, "url": "string", "description": "string", "enabled_events": [ "string" ], "status": "enabled", "disabled_reason": "string", "secret_preview": "string", "secret": "string", "created_at": "2026-10-01T09:30:00Z", "updated_at": "2026-10-01T09:30:00Z" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 422 الطلب غير صالح. يوضّح `details` كل حقل به خطأ. ```json { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "The to field is required.", "param": "to", "details": [ { "param": "to", "code": "parameter_missing", "message": "The to field is required." } ], "doc_url": "https://app.example.com/docs/errors#parameter_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing`, `parameter_invalid`, `webhook_url_invalid`, `insufficient_scope` ## حذف نقطة استقبال ``` DELETE https://api.saei.automize.sa/v1/webhook_endpoints/{id} ``` يوقف كل الإرسال إليها، بما فيه إعادة المحاولات المعلّقة. - الصلاحية: webhooks:write - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. ### الاستجابة 200 تم الحذف. ```json { "id": "string", "object": "webhook_endpoint", "deleted": true } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing` ## عرض عمليات الإرسال ``` GET https://api.saei.automize.sa/v1/webhook_endpoints/{id}/deliveries ``` كل محاولة لإرسال حدث إلى هذه النقطة، الأحدث أولًا، مع رمز HTTP الذي أجاب به خادمك. - الصلاحية: webhooks:read - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. - `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100. - `cursor` (query): قيمة `next_cursor` من الصفحة السابقة. - `status` (query): فقط عمليات الإرسال في هذه الحالة. ### الاستجابة 200 صفحة من عمليات الإرسال. ```json { "object": "list", "data": [ { "id": "del_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_delivery", "livemode": false, "webhook_endpoint_id": "string", "event_id": "string", "event_type": "string", "status": "pending", "attempts": 0, "http_status": 0, "duration_ms": 0, "response_snippet": "string", "last_error": "string", "next_attempt_at": "2026-10-01T09:30:00Z", "delivered_at": "2026-10-01T09:30:00Z", "created_at": "2026-10-01T09:30:00Z", "payload": { "id": "evt_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "event", "type": "message.delivered", "version": "2", "created_at": "2026-10-01T09:30:00Z", "livemode": false, "workspace_id": "ws_12", "data": { "object": {}, "previous_attributes": {} } } } ], "has_more": false, "next_cursor": "string" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing` ## تدوير سر التوقيع ``` POST https://api.saei.automize.sa/v1/webhook_endpoints/{id}/rotate_secret ``` يُرجع `secret` جديدًا. لمدة 24 ساعة يُوقَّع كل حدث بالسر القديم والجديد معًا، لتنشر السر الجديد دون أن يفوتك أي حدث. - الصلاحية: webhooks:write - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. ### الاستجابة 200 نقطة الاستقبال مع سرّها الجديد. ```json { "id": "we_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_endpoint", "livemode": false, "url": "string", "description": "string", "enabled_events": [ "string" ], "status": "enabled", "disabled_reason": "string", "secret_preview": "string", "secret": "string", "created_at": "2026-10-01T09:30:00Z", "updated_at": "2026-10-01T09:30:00Z" } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing` ## إرسال حدث تجريبي ``` POST https://api.saei.automize.sa/v1/webhook_endpoints/{id}/test ``` يرسل حدث `webhook.test` موقّعًا إلى هذه النقطة فقط. تابع نتيجته من قائمة عمليات الإرسال. - الصلاحية: webhooks:write - يعمل في وضع الاختبار ### المعاملات - `id` (path, مطلوب): معرّف العنصر. ### الاستجابة 202 أُضيف الحدث التجريبي لقائمة الإرسال. ```json { "id": "del_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "webhook_delivery", "livemode": false, "webhook_endpoint_id": "string", "event_id": "string", "event_type": "string", "status": "pending", "attempts": 0, "http_status": 0, "duration_ms": 0, "response_snippet": "string", "last_error": "string", "next_attempt_at": "2026-10-01T09:30:00Z", "delivered_at": "2026-10-01T09:30:00Z", "created_at": "2026-10-01T09:30:00Z", "payload": { "id": "evt_01j9x3k2m4n5p6q7r8s9t0v1w2", "object": "event", "type": "message.delivered", "version": "2", "created_at": "2026-10-01T09:30:00Z", "livemode": false, "workspace_id": "ws_12", "data": { "object": {}, "previous_attributes": {} } } } ``` ### الاستجابة 401 مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية. ```json { "error": { "type": "authentication_error", "code": "api_key_invalid", "message": "The API key is not valid.", "doc_url": "https://app.example.com/docs/errors#api_key_invalid", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 404 لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع). ```json { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such message: msg_999.", "param": "id", "doc_url": "https://app.example.com/docs/errors#resource_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الاستجابة 422 الطلب غير صالح. يوضّح `details` كل حقل به خطأ. ```json { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "The to field is required.", "param": "to", "details": [ { "param": "to", "code": "parameter_missing", "message": "The to field is required." } ], "doc_url": "https://app.example.com/docs/errors#parameter_missing", "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2" } } ``` ### الأخطاء المحتملة `resource_missing`, `parameter_invalid`