تخطَّ إلى المحتوى

Webhooks

نقطة نهاية webhook رابط HTTPS يستلم أحداثا موقّعة. كل نقاط النهاية هنا تحتاج webhooks:manage. الأحداث والتواقيع وإعادة المحاولة مشروحة في Webhooks.

الحقل النوع الوصف
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
GET/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
}
POST/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 لا تتسع باقتك لنقطة نهاية أخرى. انظر الباقات.
PATCH/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}'
DELETE/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"
GET/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"
}
POST/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"
POST/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 “الاستماع إلى الأحداث (للتطوير)”
GET/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: ready
data: {"listenerId":"lsn_3f0b8c1e-7a4d-4e52-9b6a-0c2d1e8f9a47","events":["message.delivered","message.failed"],"expiresAt":"2026-11-19T13:05:00.000Z"}
: ping
event: event
id: evt_c7e9g2i4k6m8o1q3s5u7w9y2
data: {"id":"evt_c7e9g2i4k6m8o1q3s5u7w9y2","type":"message.delivered","createdAt":"2026-11-19T13:01:12.000Z","orgId":"org_n5q8t1w4z7c0f3i6l9o2r5u8","data":{…}}
event: rotate
data: {}
الإطار المحتوى
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 عادية قبل أن يبدأ البث.