SDK

نقاط النهاية

`webhooks.list` و`get` و`create` و`update` و`delete` و`rotateSecret` و`test` و`listDeliveries`.

كل التوابع

usage.ts

const endpoint = await openemail.webhooks.create({  url: 'https://acme.com/hooks/mail',  eventTypes: ['email.sent', 'email.bounced'],  description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.webhooks.delete(endpoint.id)

نداء create هو المرة الوحيدة التي يُعاد فيها السر، عدا rotateSecret. ولا تعيده القراءة أبدًا، فخزّنه قبل أي شيء آخر. وأغفل eventTypes لتستقبل كل حدث، بما في ذلك الأحداث اللاحقة.

ليس لـrotateSecret نافذة تداخل. فالسر القديم يتوقف عن العمل فورًا، فانشر الجديد قبل التدوير. ولا تُعاد محاولته تلقائيًا أبدًا: فإعادة المحاولة ستدوّر مرة ثانية وتبطل السر الذي أعادته المحاولة الأولى.

ما يمكنك الاشتراك فيه

يُصدَّر WEBHOOK_EVENTS كي تتمكن من عرض القائمة. والأحداث أحداث **صندوق البريد** لا أحداث هذا API: فـemail.received ينطلق للبريد الذي يصل إلى التطبيق، وemail.sent ينطلق لرسالة أرسلها المحرِّر. والاشتراك ليس كمراقبة حركة API الخاصة بك.

إثبات أنه يعمل

webhook-test.ts

const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)

قيمة responseCode التي هي null تعني أنه لم تكن هناك استجابة إطلاقًا (DNS أو TLS أو انتهاء مهلة)، وهي حقيقة مختلفة عن استجابة قالت 0. ويحمل كل صف attempt وmaxAttempts، فقد تصف عدة صفوف حدثًا واحدًا: فالقيمة payload.id نفسها عبرها هي الحدث، ورقم المحاولة هو المحاولة.

المعاملات: webhooks.create

urlstringمطلوب: الوجهة التي تُرسَل إليها التسليمات بـPOST. وبـHTTPS حصرًا، ولا يجوز أن يكون المضيف `localhost` ولا اسمًا من نوع `.localhost`/`.local`/`.internal`، ولا عنوان IP حرفيًا من نوع loopback أو خاص أو CGNAT أو link-local. فهذا جلب من جهة الخادم إلى عنوان تزوّده أنت، ولذلك تعطي تلك الحالات 422 على `url`؛ ويقرأ الفحص اسم المضيف كما كُتب ولا يحلّ DNS أبدًا. والمخزَّن هو ما يسلسله محلّل URL لما أرسلته، فـ`https://acme.com` يُقرأ مجددًا `https://acme.com/`.
eventTypesWebhookEvent[]: الأحداث التي تصل إلى نقطة النهاية هذه: أي من الأسماء في `WEBHOOK_EVENTS`. ويحدّ `POST /webhooks` المصفوفة بعدد الأحداث الموجودة، فواحد فوق ذلك يعطي 422 على `eventTypes`؛ أما `PATCH` فلا يحدّها. والمحدود هو الطول فقط، والاسم المكرر يُخزَّن ويُقرأ تمامًا كما أرسلته. والإغفال أو الفراغ يُخزَّن كقائمة فارغة، ولهذا يُقرأ مجددًا `['*']`، وهو يعني كل حدث `email.*` عدا `email.replied`، أي أربعة عشر حدثًا اليوم، ولا يعني أبدًا عائلتي النطاقات أو الكبح. والعائلة المضافة لاحقًا لا تصل أبدًا إلى نقطة نهاية لم تسمّها، فلا يمكن لتكامل أن يبدأ باستقبال شكل لم يره قط بسبب إصدار جديد.
descriptionstring: تسمية لنقطة النهاية، بحد أقصى 200 حرف، كي تُقرأ قائمة الـwebhooks كأسماء لا كعمود من عناوين URL. وإن أُغفلت، خُزّنت وأُعيدت كـnull.

الاستجابة: CreatedWebhookResource

object'webhook': دائمًا `'webhook'`، وهو المميِّز نفسه الذي تعيده القراءة العادية، لأن السر مفتاح إضافي واحد على الشكل العادي لا نوع كائن مستقل. ووجود `secret` من عدمه يحدّده التابع الذي ناديته، لا هذا الحقل.
idstring: معرّف نقطة النهاية: `whe_` متبوعًا بـ24 حرفًا ست عشريًا. ويأخذه كل نداء webhook آخر: `get` و`update` و`delete` و`rotateSecret` و`test` و`listDeliveries`.
urlstring: نقطة النهاية كما خُزّنت، بعد اجتياز فحص HTTPS وفحص المضيفات المحظورة. وهي عنوان URL المحلَّل بعد إعادة تسلسله، فقارن بهذه القيمة لا بالسلسلة التي أرسلتها.
descriptionstring | null: التسمية التي أعطيتها لها، أو null إن لم تعطِ شيئًا. وطلب `update` الذي يرسل null صريحة يمسحها ويعيدها إلى null.
eventTypesWebhookEvent[] | ['*']: الأحداث المشترَك فيها، أو `['*']` حين لم تسمِّ نقطة النهاية أي حدث. والقيمة `['*']` هي طريقة عرض قائمة مخزَّنة فارغة عند القراءة ولا يمكن إرسالها مجددًا، وهي تمثّل أحداث الرسائل الثلاثة عشر لا الفهرس كله. ولا يقبل `create` و`update` إلا أسماء الأحداث الحرفية.
enabledboolean: ما إذا كانت التسليمات تُحاوَل؛ فنقطة النهاية المعطّلة تُتخطى عند إرسال الأحداث وتحتفظ بسرّها وبسجل تسليماتها. وهي true دائمًا هنا، لأن `WebhookCreate` لا يحتوي `enabled` و`WebhookPatch` وحده يحتويه.
lastDeliveryAtstring | null: طابع وقت بصيغة ISO 8601 لآخر محاولة تسليم، لا لآخر نجاح. ويُختم بعد طلب POST فاشل أيضًا، فهو يخبرك بأن نقطة النهاية جُرّبت، و`listDeliveries` يخبرك كيف سارت المحاولة. ويكون null حتى المحاولة الأولى، ولذلك هو null دائمًا في `create`.
createdAtstring: طابع وقت بصيغة ISO 8601 لوقت تسجيل نقطة النهاية. ويعيد `list` نقاط النهاية من الأحدث إلى الأقدم بحسب هذا الحقل.
secretstring: مفتاح HMAC-SHA-256 الذي يوقّع ترويسة `X-OpenEmail-Signature` في كل تسليم: `whsec_` متبوعًا بـ32 بايتًا عشوائيًا بترميز base64url، وهو ما تسلّمه إلى `verifyWebhookSignature`. ويعيده `create` و`rotateSecret` ولا شيء غيرهما. ولا تعيده القراءة أبدًا، فخزّنه الآن؛ والسر الضائع لا يمكن استبداله إلا بـ`rotateSecret`، الذي يبطل القديم فورًا.