Webhooks
نقطة نهاية webhook رابط HTTPS يستلم أحداثا موقّعة. كل نقاط النهاية هنا تحتاج webhooks:manage. الأحداث والتواقيع وإعادة المحاولة مشروحة في Webhooks.
كائن webhook
Section titled “كائن webhook”| الحقل | النوع | الوصف |
|---|---|---|
id |
string | whk_… |
url |
string | نقطة النهاية. |
events |
string[] | أنواع الأحداث المشترك فيها. |
enabled |
boolean | نقاط النهاية المعطلة لا تستلم شيئا. |
description |
string أو null | ملاحظتك. |
createdAt وupdatedAt |
string |
كائن الطلب:
| الحقل | النوع | الوصف |
|---|---|---|
id |
string | dlv_… |
webhookId |
string | |
eventId |
string | evt_…، ويُرسل أيضا في SMSFabric-Event-Id. |
eventType |
string | مثل message.delivered. |
status |
string | pending أو succeeded أو failed. |
attempts |
integer | المحاولات المنفذة، حتى 8. |
lastStatusCode |
integer أو null | آخر حالة HTTP ردت بها نقطة النهاية. |
lastError |
string أو null | مثل HTTP 500 أو timeout. |
nextAttemptAt |
string أو null | موعد المحاولة التالية. |
deliveredAt |
string أو null | وقت رد نقطة النهاية بـ 2xx. |
createdAt |
string |
عرض نقاط النهاية
Section titled “عرض نقاط النهاية”/v1/webhookswebhooks:manageيعيد كل نقاط النهاية في صفحة واحدة (nextCursor: null).
curl https://api.smsfabric.com/v1/webhooks \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "whk_p9s2v5y8b1e4h7k0n3q6t9w2", "url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "enabled": true, "description": "Order notifications", "createdAt": "2026-11-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" } ], "nextCursor": null}إنشاء نقطة نهاية
Section titled “إنشاء نقطة نهاية”/v1/webhookswebhooks:manageيعيد 201 مع نقطة النهاية وsigningSecret الخاص بها، ولا يظهر إلا هذه المرة. يدعم Idempotency-Key. يُسجل في التدقيق باسم webhook.created.
| حقل المحتوى | النوع | إلزامي | الوصف | القيود |
|---|---|---|---|---|
url |
string | نعم | حيث تُرسل الأحداث. | https وعنوان عام، حتى 2048 حرفا. |
events |
string[] | نعم | أنواع الأحداث المطلوبة. | واحد على الأقل من: message.queued وmessage.sent وmessage.delivered وmessage.failed وmessage.received وdevice.online وdevice.offline وverification.approved وverification.expired وverification.blocked وcampaign.started وcampaign.completed. |
description |
string | لا | ملاحظتك. | حتى 255 حرفا. |
curl https://api.smsfabric.com/v1/webhooks \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "description": "Order notifications"}'{ "id": "whk_p9s2v5y8b1e4h7k0n3q6t9w2", "url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "enabled": true, "description": "Order notifications", "createdAt": "2026-11-19T13:10:00.000Z", "updatedAt": "2026-11-19T13:10:00.000Z", "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}| الخطأ | متى |
|---|---|
400 ssrf_blocked |
الرابط ليس https، أو يشير مضيفه إلى عنوان خاص أو loopback أو link-local. |
400 validation_failed |
لا أحداث، أو نوع حدث غير معروف. |
403 plan_limit_reached |
لا تتسع باقتك لنقطة نهاية أخرى. انظر الباقات. |
تحديث نقطة نهاية
Section titled “تحديث نقطة نهاية”/v1/webhooks/:idwebhooks:manageكل الحقول اختيارية: url وevents وenabled وdescription، بقيود الإنشاء. يُفحص url الجديد مجددا. يعيد نقطة النهاية (دون السر). يُسجل في التدقيق باسم webhook.updated.
curl -X PATCH https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'حذف نقطة نهاية
Section titled “حذف نقطة نهاية”/v1/webhooks/:idwebhooks:manageيعيد 204. يُسجل في التدقيق باسم webhook.deleted.
curl -X DELETE https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"عرض الطلبات
Section titled “عرض الطلبات”/v1/webhooks/:id/deliverieswebhooks:manageمحاولات الإرسال لنقطة نهاية واحدة، من الأحدث إلى الأقدم، مقسمة إلى صفحات عبر limit وcursor.
curl "https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/deliveries?limit=1" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "dlv_f3i6l9o2r5u8x1a4d7g0j3m6", "webhookId": "whk_p9s2v5y8b1e4h7k0n3q6t9w2", "eventId": "evt_c7e9g2i4k6m8o1q3s5u7w9y2", "eventType": "message.delivered", "status": "pending", "attempts": 2, "lastStatusCode": 503, "lastError": "HTTP 503", "nextAttemptAt": "2026-11-19T10:21:09.000Z", "deliveredAt": null, "createdAt": "2026-11-19T10:15:09.460Z" } ], "nextCursor": "ZGx2X2YzaTZsOW8ycjV1OHgxYTRkN2cwajNtNg"}إعادة إرسال طلب
Section titled “إعادة إرسال طلب”/v1/webhooks/:id/deliveries/:deliveryId/replaywebhooks:manageيضع الحدث نفسه في الطابور مجددا، بمعرّف الحدث نفسه وتوقيع جديد. يعيد 202 مع الطلب (status: "pending").
curl -X POST https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/deliveries/dlv_f3i6l9o2r5u8x1a4d7g0j3m6/replay \ -H "X-Api-Key: $SMSFABRIC_API_KEY"إرسال حدث تجريبي
Section titled “إرسال حدث تجريبي”/v1/webhooks/:id/testwebhooks:manageيرسل حدث webhook.test إلى نقطة النهاية هذه، موقّعا كأي حدث آخر. يعيد 202 مع الطلب الجديد.
curl -X POST https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/test \ -H "X-Api-Key: $SMSFABRIC_API_KEY"المحتوى الذي تستلمه نقطة النهاية:
{ "id": "evt_e9g2i4k6m8o1q3s5u7w9y2a4", "type": "webhook.test", "createdAt": "2026-11-19T13:12:00.000Z", "orgId": "org_n5q8t1w4z7c0f3i6l9o2r5u8", "data": { "message": "This is a test event from SMSFabric." }}الاستماع إلى الأحداث (للتطوير)
Section titled “الاستماع إلى الأحداث (للتطوير)”/v1/webhooks/listenwebhooks:manageأداة للتطوير: بث أحداث (server-sent events) يحمل أحداث webhook الخاصة بمؤسستك لحظة وقوعها، عبر اتصال يفتحه جهازك، فلا تحتاج رابطا عاما. يستخدمه سطر الأوامر (smsfabric listen) والدالة webhooks.listen() في الحزمة. ويحمل كل حدث تنتجه مؤسستك، سواء اشتركت فيه نقطة نهاية أم لا. يعمل بمفتاح API أو برمز مستخدم. يُسجل في التدقيق باسم webhook.listen_started.
| معامل الاستعلام | النوع | إلزامي | الوصف |
|---|---|---|---|
events |
string | لا | أنواع أحداث مفصولة بفواصل، مثل message.sent,message.delivered. اتركه لتستقبل كل الأحداث. النوع غير المعروف يعيد 400 validation_failed. |
curl -N "https://api.smsfabric.com/v1/webhooks/listen?events=message.delivered,message.failed" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"الاستجابة 200 مع Content-Type: text/event-stream:
event: readydata: {"listenerId":"lsn_3f0b8c1e-7a4d-4e52-9b6a-0c2d1e8f9a47","events":["message.delivered","message.failed"],"expiresAt":"2026-11-19T13:05:00.000Z"}
: ping
event: eventid: evt_c7e9g2i4k6m8o1q3s5u7w9y2data: {"id":"evt_c7e9g2i4k6m8o1q3s5u7w9y2","type":"message.delivered","createdAt":"2026-11-19T13:01:12.000Z","orgId":"org_n5q8t1w4z7c0f3i6l9o2r5u8","data":{…}}
event: rotatedata: {}| الإطار | المحتوى |
|---|---|
ready |
الإطار الأول: listenerId (lsn_…) وevents (الفارغة تعني كل الأحداث) وexpiresAt، وهو وقت إنهاء الخادم لهذا البث. |
event |
حدث webhook واحد. id هو معرف الحدث، وdata هو محتوى JSON نفسه الذي تستلمه نقطة النهاية بايتا ببايت، فيمكنك توقيعه وتمريره دون تغيير. رسائل Verify محجوبة كما في webhooks. |
rotate |
يُرسل قبل نهاية البث بعشر ثوان. افتح البث التالي الآن، وأغلق هذا حين يرسل الجديد ready. الحدث الذي يظهر في البثين يحمل id نفسه. |
: ping |
سطر تعليق كل 15 ثانية يبقي الاتصالات الخاملة مفتوحة. تجاهله. |
سلوك البث:
- مدة البث. ينهي الخادم كل بث بعد 5 دقائق، فيتوقف المفتاح الملغى أو المؤسسة الموقوفة عن الاستقبال خلال هذه المدة.
- لا إعادة. الأحداث التي تقع ولا بث متصل لا تُخزن ولا يُعاد إرسالها.
- لا توقيع. الإطارات غير موقعة لأن البث نفسه موثق. يوقع سطر الأوامر ما يمرره بسره الخاص.
- القارئ البطيء. يُفصل العميل الذي يتوقف عن القراءة حين ينتظره 1 MiB.
للإنتاج، سجّل نقطة نهاية: تحصل على التواقيع وإعادة المحاولة نحو 24 ساعة وسجل الطلبات.
| الخطأ | متى |
|---|---|
400 validation_failed |
events يذكر نوع حدث غير معروف. |
403 missing_permission |
المفتاح أو المستخدم لا يملك webhooks:manage. |
429 too_many_listeners |
لدى مؤسستك 5 بثوث مفتوحة بالفعل. تخبرك Retry-After متى يحرر البث المفقود مكانه (خلال 45 ثانية)، والبث الذي تغلقه يحرره فورا. |
429 rate_limited |
فُتح أكثر من 30 بثا في دقيقة بمفتاح أو مستخدم واحد. |
تصل الأخطاء استجابة application/problem+json عادية قبل أن يبدأ البث.