تلقَّ تحديثات الرسائل دون استعلامات متكررة
بدلاً من الاستعلام المستمر عن حالة كل رسالة، استقبل إشعارات Webhook عند وقوع الأحداث المدعومة.
تقليل استعلامات API
استقبل تحديثات حالات الرسائل عبر Webhook، دون الحاجة إلى إرسال طلبات متكررة للتحقق من حالتها.
أتمتة إجراءات العمل
استخدم الإشعارات الواردة لتحديث السجلات والتقارير أو تشغيل الإجراءات المناسبة داخل نظامك.
متابعة حالات الرسائل
تابع تغيّرات حالات الرسائل والرسائل الواردة من خلال الإشعارات التي ترسلها TurkeySMS إلى نظامك.
حدث واحد، أربع خطوات
إرسال الرسالة أو استقبالها
ترسل رسالة نصية عبر TurkeySMS باستخدام لوحة التحكم أو API، أو تصل رسالة إلى رقم 0850 الخاص بك.
تسجيل الحدث
عند وقوع حدث مدعوم، مثل تحديث حالة الرسالة، يُسجّل النظام الحدث ويوقّع الإشعار إذا كان مفتاح التوقيع معرَّفاً.
إرسال إشعار Webhook
ترسل TurkeySMS بيانات الحدث إلى عنوان HTTPS الذي حددته.
معالجة الإشعار
يتحقق نظامك من الإشعار، ويعيد استجابة 2xx، ثم يعالج البيانات لتنفيذ الإجراء المناسب.
المخطط للتوضيح فقط، وليس تعهداً بزمن محدد. وطريقة معالجة الحدث داخل نظامك تعتمد على التكامل لديك.
ما الأحداث التي يمكنك استقبالها؟
تختار الأحداث التي تريد استقبالها من إعدادات Webhook.
sms.sent
متاح الآنعند تسليم رسالتك إلى المشغّل.
sms.delivered
متاح الآنعند وصول تقرير تسليم ناجح من المشغّل.
sms.received
متاح الآنعند وصول رسالة إلى رقم 0850 الخاص بك. ولأنه يتضمن نص الرسالة، لا يُرسل إلا إذا اخترته صراحةً في الإعدادات.
inbound.matched
متاح الآنعند تنفيذ إجراء "استدعاء Webhook" في إحدى قواعد أتمتة الرسائل الواردة. ويُرسل إلى أول Webhook مفعّل في حسابك. الرسائل الواردة
key.test
متاح الآنعند الضغط على زر «اختبار» في اللوحة؛ لتجربة الاتصال بعنوانك.
لا يُرسل نص الرسالة في أحداث الرسائل الصادرة؛ أما أحداث الرسائل الواردة فتتضمن نص الرسالة ورقم المرسل.
اطّلع على محتوى الإشعار
اختر حدثاً، واستعرض ترويسات الطلب ومحتوى JSON، ثم جرّب بنفسك كيف يتكوّن التوقيع.
البيانات المعروضة للتوضيح، وقد استُخدمت قيم تجريبية. تعمل هذه التجربة داخل متصفحك، ولا يُرسل أي طلب.
{
"id": "27f38025030d060f3e3b760b318b406e",
"event": "sms.delivered",
"created_at": "2026-10-01T15:30:03+03:00",
"timestamp": 1790857803,
"data": {
"message_id": 518431556,
"bulk_id": "1259383818",
"to": "905xxxxxxxxx",
"sender_id": "BASLIGIM",
"parts": 1,
"source": "api",
"key_id": 1001,
"sent_at": "2026-10-01T15:28:31+03:00",
"done_at": "2026-10-01T15:28:33+03:00",
"operator_status": "Message delivered to handset",
"status": "delivered"
}
}مفتاح التوقيع في حسابك (الذي يوقّع الإشعار): demo-secret
جارٍ الحساب…
هذه التجربة لا تفحص النافذة الزمنية (300 ثانية)؛ أما نظامك الفعلي فيجب أن يفحص قيمة t= في التوقيع أيضاً.
- اقرأ محتوى الطلب كما وصل، دون إعادة تنسيقه.
- افصل من قيمة X-TurkeySMS-Signature-V2 الجزأين t (الوقت) وv1 (التوقيع).
- احسب قيمة HMAC لقيمة t متبوعةً بنقطة ثم المحتوى، باستخدام مفتاح التوقيع لديك.
- قارن النتيجة بالتوقيع مقارنةً ثابتة الزمن، وتأكد أن قيمة t حديثة (300 ثانية)؛ وإن لم تتطابق فأعد الرمز 401.
ملاحظة: استجابة HTTP 2xx تعني أن الحدث استُلم، ولا تعني أن العملية في نظامك اكتملت بنجاح. عالج كل حدث مرة واحدة بالاعتماد على معرّف الإرسال.
إشعارات موقّعة يمكن التحقق منها
توقيع HMAC
عند تعريف مفتاح التوقيع تُوقَّع الإشعارات بـ HMAC من نوع SHA‑256 أو SHA‑512، فتتحقق من مصدر الإشعار وسلامة محتواه. وإذا لم يُعرَّف المفتاح فلا تُرسل ترويسات التوقيع.
توقيع بطابع زمني (V2)
يشمل توقيع V2 الطابعَ الزمني أيضاً. ويستطيع نظامك، بفحص الوقت في التوقيع، منع إعادة استخدام الطلبات القديمة.
معرّف الإرسال
معرّف كل حدث لا يتغير بين المحاولات؛ وبه تستبعد الأحداث المكررة.
لا إرسال إلى العناوين المحلية
لا تُقبل localhost وعناوين الشبكات الخاصة كعنوان Webhook.
ماذا يحدث إذا لم يستجب خادمك؟
إذا تعذّر تسليم الإشعار إلى خادمك، يتعامل النظام مع المحاولة غير الناجحة وفق آلية إعادة المحاولة التالية.
إعادة المحاولة عند الخطأ
التوقف عند الاستجابة 400
الإيقاف المؤقت
قد يصلك الإشعار نفسه أكثر من مرة. لذلك ننصح باستخدام معرّف الحدث لتجنّب معالجة الإشعارات المكررة. استجب أولاً ثم عالج: سجّل الحدث وأعد 2xx فوراً؛ ويجب أن يستجيب خادمك خلال 10 ثوانٍ تقريباً.
تابع كل إشعار من لوحة التحكم
راجع إشعارات Webhook وحالات إرسالها ونتائج المحاولات من مكان واحد، لتسهيل متابعة التكامل واكتشاف المشكلات.
كيف تستفيد من Webhook في أعمالك؟
ربط نظام CRM
اربط تحديثات حالات الرسائل بسجلات العملاء داخل نظام إدارة علاقات العملاء.
sms.deliveredمتابعة الطلبات
استخدم حالات الرسائل لتحديث معلومات التواصل المرتبطة بالطلبات.
sms.sentsms.deliveredإعداد التقارير
أرسل بيانات حالات الرسائل إلى نظام التقارير والتحليلات لديك.
sms.sentsms.deliveredمتابعة الرسائل الواردة
انقل ردود العملاء إلى نظام الدعم أو الطلبات لديك كسجلات. الرسائل الواردة
sms.receivedفعّل تكامل Webhook في ثلاث خطوات
إعداد عنوان الاستقبال
جهّز عنوان HTTPS في تطبيقك لاستقبال إشعارات Webhook، ومفتاح API في حسابك ليرتبط به Webhook.
ضبط التكامل
من حسابي ← مركز API ← الأمان و IP ← Webhook: اختر مفتاح API، وأضف عنوان الاستقبال ومفتاح التوقيع، وحدّد الأحداث التي تريدها.
اختبار الإشعارات
جرّب الاتصال بزر «اختبار» أو بمحاكي Webhook، ثم تحقّق من استقبال البيانات والتوقيع ومعالجة الأحداث داخل نظامك، وتابع الإرسال من مركز الـ Webhook.
ماذا تحتاج للبدء؟
الحساب
مفتاح API ومفتاح التوقيع
عنوان عام
Webhook
هل تحتاج مساعدة في الإعداد؟ نتصل بك
الأسئلة الشائعة
ما هو Webhook، وما الفرق بينه وبين SMS API؟
مع SMS API ترسل أنت الطلب إلى TurkeySMS (مثل إرسال رسالة أو الاستعلام عن حالتها). أما في Webhook فالاتجاه معاكس: عند وقوع حدث ترسل TurkeySMS إشعاراً إلى العنوان الذي حددته. وهكذا لا تحتاج إلى الاستعلام من API باستمرار لمعرفة الحالة.
ما أحداث SMS التي أستطيع تلقي إشعارات عنها؟
sms.sent (عند تسليم الرسالة إلى المشغّل)، وsms.delivered (عند وصول تقرير التسليم)، وsms.received (عند وصول رسالة إلى رقم 0850 الخاص بك، إذا اخترته صراحةً)، وinbound.matched (عند تنفيذ إجراء "استدعاء Webhook" في أتمتة الرسائل الواردة)، وkey.test (زر الاختبار).
متى تُرسل إشعارات Webhook؟
بعد وقوع الحدث يدخل قائمة الانتظار ثم يُرسل إلى عنوانك. لا نتعهد بزمن محدد لوصول الإشعار؛ إذ يتأثر الزمن بتقرير المشغّل وإعادة المحاولات واستجابة خادمك. ويمكنك دائماً معرفة الحالة النهائية للرسالة من تقارير الرسائل.
ماذا يحدث إذا لم يستجب خادمي؟
إذا أعاد خادمك استجابة 5xx أو انتهت المهلة، يُعاد إرسال الحدث على فترات متزايدة. أما الاستجابة 400 فتُعدّ خطأً نهائياً ولا يُعاد الإرسال بعدها. ويجب أن يستجيب خادمك خلال 10 ثوانٍ تقريباً.
هل يمكن أن يصل الحدث نفسه مرتين؟
نعم، مثلاً عند إعادة المحاولة بعد انتهاء المهلة. معرّف كل حدث (X-TurkeySMS-Delivery) لا يتغير بين المحاولات؛ فإذا وصلك معرّف سبق أن عالجته فأعد استجابة 2xx دون معالجته مجدداً.
كيف أتحقق من توقيع Webhook؟
عند تعريف مفتاح التوقيع يصل كل طلب مع الترويسة X-TurkeySMS-Signature-V2؛ وإذا لم يُعرَّف المفتاح فلا تُرسل ترويسات التوقيع. احسب قيمة HMAC من المحتوى كما وصل ومن الطابع الزمني في التوقيع، ثم قارن بينهما؛ التفاصيل وأمثلة الأكواد في توثيق API.
كيف أختبر تكامل Webhook؟
استخدم زر «اختبار» في حسابي ← مركز API ← الأمان و IP ← Webhook: يرسل الحدث key.test ويعرض رمز HTTP والمدة. أما محاكي Webhook فيرسل الحدث الذي تختاره بتوقيع حقيقي ومع العلامة "simulated": true. ثم راجع سجلات التسليم في مركز الـ Webhook.
هل توجد رسوم إضافية لاستخدام Webhook؟
لا، لا توجد رسوم إضافية لاستخدام Webhook. وتحتاج أحداث الإرسال إلى إرسال رسائل (باقة رسائل)، وأحداث الرسائل الواردة إلى رقم 0850 مخصّص لحسابك.
إذا أوقفت Webhook مؤقتاً، هل تضيع الأحداث؟
لا تُرسل الأحداث إلى Webhook الموقوف. وعند إعادة تفعيله لا تُرسل أحداث فترة الإيقاف؛ ويمكنك معرفة حالات تلك الفترة من تقارير الرسائل.
إلى أي عنوان يُرسل إجراء "استدعاء Webhook"؟
يُرسل إجراء "استدعاء Webhook" في أتمتة الرسائل الواردة الحدث "inbound.matched" إلى أول Webhook مفعّل في حسابك.
هل يصل نص الرسالة عبر Webhook؟
لا يُرسل نص الرسالة في أحداث الرسائل الصادرة (sms.sent، sms.delivered). أما أحداث الرسائل الواردة (sms.received، inbound.matched) فتتضمن نص الرسالة ورقم المرسل؛ فاحفظ هذه البيانات وفق قانون حماية البيانات الشخصية (KVKK).
اربط تحديثات الرسائل النصية بنظامك
استكشف تكامل Webhook من TurkeySMS، وتعرّف على طريقة استقبال إشعارات حالات الرسائل ومعالجتها داخل تطبيقك. إنشاء الحساب مجاني.