كيف تعمل
سجّل نقطة استقبال من الإعدادات ← المطورون ← الويب هوك، أو عبر POST /webhook-endpoints (بصلاحية webhooks:manage، ويجب أن يملك صاحب المفتاح صلاحية إدارة إعدادات المنشأة). يُرسل كل حدث تشترك فيه نقطة الاستقبال إليها بطلب POST عبر HTTPS بمحتوى JSON، عادةً خلال دقيقة. تتبع نقطة الاستقبال منشأة واحدة، ولا تستقبل نقاط استقبال منشأة الاختبار إلا أحداثها التجريبية (livemode: false).
لا تشترك نقطة الاستقبال إلا في الأحداث التي يستطيع المفتاح أو التطبيق الذي سجّلها قراءتها: أحداث الفواتير والإشعارات تحتاج إلى invoices:read، وأحداث العملاء إلى customers:read. عبر الواجهة البرمجية تُحفظ * بهذه الأنواع تحديدًا، ويُرفض أي نوع آخر برمز 422. وتتبع نقطة الاستقبال التي يسجّلها تطبيق اتصالَ ذلك التطبيق: عندما تفصل المنشأة التطبيق تُوقف نهائيًا (disabled_reason: connection_revoked)، ولا تستقبل أبدًا حدثًا لا تغطيه صلاحيات الاتصال الحالية. ولا يرى التطبيق ولا يغيّر إلا نقاط الاستقبال التي سجّلها.
| الحدث | متى |
|---|---|
invoice.created |
إنشاء مسودة فاتورة، من أي قناة. |
invoice.issued |
إصدار مسودة. |
invoice.zatca_status_changed |
تغير الحالة لدى الهيئة، مثلًا من pending إلى cleared أو rejected. ويحمل data.previous_zatca_status الحالة السابقة. |
invoice.payment_recorded |
تسجيل دفعة أو إلغاؤها أو حذفها، ويبيّن data.payment.status أيّها. |
invoice.paid، invoice.overdue |
سداد الفاتورة بالكامل، أو تأخرها. |
invoice.cancelled |
إلغاء مسودة. |
credit_note.issued، debit_note.issued |
إصدار إشعار. |
credit_note.zatca_status_changed، debit_note.zatca_status_changed |
تغير حالة الإشعار لدى الهيئة. |
customer.created، customer.updated |
إضافة عميل أو تعديله. |
ping |
إرسال حدث تجريبي (POST /webhook-endpoints/{id}/test). |
المستندات المستوردة من نظام آخر والأرصدة الافتتاحية سجلٌّ سابق، ولا تُنشئ أحداثًا.
الترويسات
WF-Event-Id: معرّف الحدث (evt_…)، وهو نفسه في كل إعادة محاولة أو إعادة إرسال. أزل التكرار به.WF-Event-Type: نوع الحدث.WF-Delivery-Id: معرّف الإرسال (whd_…)، للدعم ولإعادة الإرسال.WF-Api-Version: صيغة المحتوى،2026-11-01، وتُثبَّت لنقطة الاستقبال عند إنشائها.WF-Signature: بالصيغةt=<الوقت بنظام يونكس>,v1=<التوقيع>، كما يلي.
المحتوى
المحتوى هو {"id": "evt_…", "type": "invoice.issued", "api_version": "2026-11-01", "created_at": "…", "livemode": true, "company_id": 42, "connection_id": null, "data": {"object": {…}}}. وdata.object هو الفاتورة أو الإشعار أو العميل كما يعيده GET تمامًا، كما كان لحظة حفظ التغيير. المخطط مذكور تحت webhooks في وثيقة OpenAPI.
التوقيع
لكل نقطة استقبال سرّ (whsec_…) يُعرض مرة واحدة عند إنشائها وعند تجديده. وv1 هو HMAC-SHA256 بالنظام الست عشري لـ t + "." + المحتوى الخام، بمفتاح هو السرّ كاملًا. ارفض t إذا ابتعد أكثر من 300 ثانية عن ساعتك وقارن بزمن ثابت؛ في PHP: hash_equals(hash_hmac('sha256', $t.'.'.$rawBody, $secret), $v1). ولمدة 24 ساعة بعد التجديد يُرسل v1 ثانٍ موقّع بالسرّ السابق؛ اقبل أيًّا منهما.
التسليم وإعادة المحاولة
- أجب بأي رمز 2xx خلال 8 ثوانٍ. أما إعادة التوجيه أو انتهاء المهلة أو أي رمز آخر ففشل.
- يُعاد الإرسال الفاشل بعد 1 و5 و30 دقيقة، ثم بعد 2 و6 و12 و24 ساعة (نحو 45 ساعة إجمالًا)، ثم يتوقف. ويمكنك إعادة أي إرسال يدويًا.
- مرة واحدة على الأقل ودون ترتيب مضمون: أزل التكرار بمعرّف الحدث، واقرأ الكائن مجددًا حين تحتاج حالته الحالية.
- تُوقَف نقطة الاستقبال التي تفشل 100 مرة متتالية دون أي نجاح لمدة 72 ساعة، ويُبلَّغ صاحبها بالبريد. شغّلها مجددًا من لوحة التحكم أو عبر
PATCH("status": "active"). - يجب أن تكون نقطة الاستقبال عنوان
httpsعامًا على المنفذ 443 أو 8443، باسم نطاق (لا عنوان IP) لا يشير إلا إلى عناوين عامة. يُتحقق من ذلك عند التسجيل وقبل كل إرسال، ولا تُتبع إعادة التوجيه أبدًا. - تُحفظ أول 512 بايتًا من ردّك مع الإرسال، فلا تُعِد فيه أي أسرار.
الاستعلام الدوري بديلًا
يعرض GET /events (بصلاحية invoices:read، وتحتاج أحداث العملاء أيضًا customers:read) الأحداث نفسها، الأحدث أولًا، وبالمحتوى data نفسه. تُسجَّل الأحداث ما دامت للمنشأة نقطة استقبال مفعّلة، وتُحفظ 30 يومًا.
صفحات ذات صلة
جاهز للبدء؟
الوصول إلى الواجهة البرمجية ضمن باقات: الأعمال والمؤسسات. أنشئ مفتاحًا من الإعدادات ← مفاتيح API وأرسل أول طلب خلال دقائق.