Webhook پیامک چیست و چگونه گزارش ارسال را لحظه ای دریافت کنیم؟

ارسال موفق درخواست به API پیامک، به این معنا نیست که پیام حتما به گوشی مخاطب رسیده است. ممکن است پیام در صف اپراتور بماند، با تاخیر تحویل شود، شماره مقصد نامعتبر باشد یا ارسال در یکی از مراحل شبکه با خطا مواجه شود. Webhook پیامک این فاصله اطلاعاتی را برطرف می‌کند و تغییر وضعیت هر پیام را به‌صورت خودکار به نرم افزار، سایت یا CRM برمی‌گرداند.

Webhook پیامک چیست؟

وب هوک پیامک یک آدرس اینترنتی در نرم افزار شماست که سامانه پیامکی پس از تغییر وضعیت SMS، اطلاعات گزارش ارسال را به آن می‌فرستد. به‌جای اینکه نرم افزار مرتبا API را برای یافتن وضعیت جدید بررسی کند، پنل پیامکی رویدادهایی مانند تحویل شدن، ناموفق بودن یا منقضی شدن پیام را معمولا با یک درخواست HTTP به Callback URL ارسال می‌کند. برای استفاده مطمئن از Webhook باید شناسه پیام، وضعیت، زمان رویداد، امنیت درخواست و کنترل گزارش های تکراری در نظر گرفته شود.

Webhook پیامک دقیقا چه کاری انجام می دهد؟

Webhook یک روش ارتباط رویدادمحور یا Event-Driven میان دو سیستم است. در این مدل، نرم افزار شما منتظر یک رویداد مشخص نمی‌ماند تا خودش آن را استعلام کند؛ بلکه سامانه پیامکی به‌محض دریافت وضعیت جدید، اطلاعات را به آدرسی که از قبل تعریف شده ارسال می‌کند.

این آدرس ممکن است در مستندات فنی با نام‌های زیر دیده شود:

• Webhook URL
• Callback URL
• Delivery Report URL
• DLR URL

برای مثال، یک فروشگاه اینترنتی پس از ثبت سفارش، از طریق API پیامک اطلاع رسانی ارسال می‌کند. پاسخ اولیه API معمولا فقط نشان می‌دهد که درخواست پذیرفته شده و یک شناسه پیام ایجاد شده است. اگر نرم افزار با فریم‌ورکی مانند Laravel توسعه یافته باشد، همان ساختاری که برای اتصال Laravel به API پیامک استفاده شده، باید شناسه پیام را نیز در پایگاه داده نگه دارد تا گزارش برگشتی قابل تطبیق باشد. چند ثانیه یا چند دقیقه بعد، اپراتور وضعیت نهایی یا موقت پیام را اعلام می‌کند و سامانه پیامکی این گزارش را از طریق Webhook به نرم افزار شما می‌فرستد.

فرایند دریافت گزارش ارسال با Webhook چگونه است؟

1. ارسال پیامک از نرم افزار

وب‌سایت، CRM یا اپلیکیشن درخواست ارسال پیام را از طریق API به سامانه پیامکی منتقل می‌کند. این پیام می‌تواند کد ورود، تایید سفارش، یادآوری پرداخت، وضعیت ارسال کالا یا هر پیام تراکنشی دیگری باشد.

2. دریافت شناسه پیام

سامانه پس از پذیرش درخواست، یک شناسه یکتا یا Message ID برمی‌گرداند. این شناسه باید در کنار شماره گیرنده، متن یا نوع پیام، زمان ارسال و شناسه عملیات اصلی ذخیره شود. اگر Message ID ثبت نشود، پس از دریافت Webhook مشخص نیست گزارش دریافتی مربوط به کدام پیام یا کدام کاربر بوده است.

3. انتقال پیام به اپراتور

سامانه پیام را وارد مسیر اپراتوری می‌کند. در این مرحله ممکن است وضعیت‌هایی مانند Accepted ،Queued یا Sent ثبت شوند. این وضعیت‌ها معمولا به معنای پذیرش یا انتقال پیام در یکی از مراحل هستند و لزوما تحویل نهایی به گوشی را تأیید نمی‌کنند.

4. دریافت Delivery Report

اپراتور پس از تحویل پیام یا وقوع خطا، یک گزارش وضعیت یا Delivery Report تولید می‌کند. این گزارش می‌تواند نشان دهد که پیام تحویل شده، ناموفق بوده، منقضی شده یا هنوز نتیجه نهایی دریافت نکرده است.

در بسیاری از موارد، علت ناموفق‌بودن پیام به عواملی مانند خاموش‌بودن طولانی گوشی، شماره نامعتبر، محدودیت اپراتور یا قرارگرفتن شماره در فهرست مسدود مربوط است؛ به همین دلیل تحلیل درست دلایل Fail شدن پیامک باید بر اساس کد وضعیت واقعی انجام شود، نه صرفاً برداشت ظاهری از عبارت «ارسال نشد».

5. ارسال Callback به نرم افزار

سامانه پیامکی اطلاعات گزارش را با یک درخواست HTTP، معمولا از نوع POST، به Webhook URL ارسال می‌کند. اطلاعات برگشتی ممکن است شامل شناسه پیام، وضعیت جدید، زمان ثبت وضعیت، کد خطا و شماره گیرنده باشد.

6. ثبت و پردازش وضعیت

نرم افزار پس از دریافت گزارش باید رکورد متناظر را پیدا کند، وضعیت آن را به‌روزرسانی کند و در صورت نیاز عملیات بعدی را انجام دهد.

برای نمونه:

• پیام تحویل شده در CRM ثبت شود.
• پیام ناموفق برای بررسی پشتیبانی علامت‌گذاری شود.
• پیام بلاتکلیف پس از زمان مشخص دوباره استعلام شود.
• خطاهای پرتکرار در داشبورد مانیتورینگ نمایش داده شوند.

تفاوت Webhook پیامک با API چیست؟

Webhook و API دو ابزار جایگزین نیستند؛ معمولا در کنار هم استفاده می‌شوند.

در API، نرم افزار شما از سامانه درخواست انجام یک کار را دارد. در Webhook، سامانه وقوع یک رویداد را به نرم‌افزار اطلاع می‌دهد. برای مثال، API پیامک را ارسال می‌کند و Webhook نتیجه مسیر همان پیام را برمی‌گرداند.

تفاوت Webhook با Polling چیست؟

در روش Polling، نرم افزار در فاصله‌های زمانی مشخص از API سؤال می‌کند که وضعیت پیام تغییر کرده است یا نه. برای مثال، هر 30 ثانیه وضعیت صدها پیام استعلام می‌شود؛ حتی اگر هیچ تغییری رخ نداده باشد.

این معماری در حجم پایین قابل استفاده است، اما با افزایش تعداد پیام‌ها، تعداد درخواست‌های غیرضروری نیز بالا می‌رود. در چنین شرایطی، محدودیت‌هایی مانند Rate Limit در API پیامک مستقیما بر طراحی سیستم اثر می‌گذارند، زیرا استعلام بیش‌ازحد می‌تواند باعث خطا، کندی یا مسدودشدن موقت درخواست‌ها شود.

معماری مطمئن معمولا ترکیبی است. Webhook مسیر اصلی دریافت وضعیت محسوب می‌شود و Polling فقط برای پیام‌هایی اجرا می‌شود که برای مدت غیرعادی در وضعیت موقت باقی مانده‌اند.

Webhook پیامک چه اطلاعاتی برمی‌گرداند؟

ساختار دقیق گزارش به سرویس‌دهنده بستگی دارد، اما معمولاً این اطلاعات در Callback دیده می‌شوند:

• Message ID
• شماره گیرنده
• وضعیت پیام
• زمان ثبت وضعیت
• کد خطا
• توضیح خطا
• شناسه درخواست
• شماره یا خط فرستنده
• اطلاعات اپراتور یا مسیر ارسال

نرم افزار نباید صرفا به متن وضعیت وابسته باشد. بهتر است کدهای رسمی سامانه به مجموعه‌ای از وضعیت‌های داخلی استاندارد تبدیل شوند.

برای مثال:

• Delivered → تحویل شده
• Failed و Rejected → ناموفق
• Pending و Queued → در انتظار
• Expired → منقضی‌شده

این نگاشت باعث می‌شود اگر نام یا ساختار وضعیت‌ها در سامانه تغییر کرد، منطق کسب و کار کمتر آسیب ببیند.

کاربردهای Webhook پیامک

ثبت وضعیت پیامک های OTP

در سامانه های ورود یا احراز هویت، Webhook مشخص می‌کند که کد یک‌بارمصرف فقط وارد صف شده یا واقعا تحویل شبکه شده است.

البته دریافت وضعیت Delivered به‌تنهایی امنیت احراز هویت را تضمین نمی‌کند. زمان انقضای کد، محدودیت تعداد تلاش، جلوگیری از درخواست مکرر و محافظت در برابر سوءاستفاده همچنان ضروری هستند. در طراحی احراز هویت پیامکی با OTP باید وضعیت تحویل فقط یکی از سیگنال‌های مانیتورینگ باشد، نه معیار تأیید هویت کاربر.

هماهنگ سازی CRM

در CRM می‌توان وضعیت هر پیام را کنار اطلاعات مشتری ذخیره کرد. تیم فروش یا پشتیبانی در این حالت می‌داند پیام اطلاع‌رسانی تحویل شده یا به دلیل خطا به مخاطب نرسیده است. این داده به‌خصوص زمانی مفید است که کارشناس قبل از تماس با مشتری بخواهد بداند پیام قبلی دریافت شده است یا خیر.

کنترل پیام های تراکنشی

پیام‌های مرتبط با سفارش، رزرو، پرداخت و ارسال کالا معمولا بخشی از فرایند عملیاتی کسب و کار هستند. اگر این پیام‌ها تحویل نشوند، ممکن است مشتری تصور کند سفارش ثبت نشده یا عملیات ناقص مانده است. Webhook کمک می‌کند پیام‌های ناموفق سریع‌تر شناسایی شوند و قبل از تبدیل‌شدن به شکایت مشتری بررسی شوند.

تحلیل کیفیت ارسال

با ثبت گزارش های تحویل می‌توان نرخ Delivered ،Failed ،Expired و Pending را بر اساس زمان ارسال، اپراتور، نوع پیام یا گروه مخاطبان بررسی کرد. این تحلیل به کسب‌وکار کمک می‌کند بفهمد مشکل از متن پیام، کیفیت شماره‌ها، زمان ارسال، مسیر اپراتوری یا زیرساخت نرم افزار است.

اجرای فرایندهای خودکار

Webhook می‌تواند شروع‌کننده عملیات بعدی باشد. برای مثال:

• پس از تحویل پیام، زمان اطلاع‌رسانی ثبت شود.
• در صورت خطای قطعی، تیکت پشتیبانی ساخته شود.
• پیام‌های ناموفق وارد صف بررسی شوند.
• وضعیت سفارش در داشبورد داخلی به‌روزرسانی شود.

در سامانه های پرترافیک بهتر است این عملیات مستقیما داخل درخواست Webhook انجام نشود. قرار دادن رویدادها در صف و پردازش جداگانه، همان منطقی است که در معماری‌های مبتنی بر AMQP و Message Queue برای جلوگیری از فشار ناگهانی و ازدست‌رفتن داده استفاده می‌شود.

مهم‌ترین مزایای Webhook پیامک

• دریافت خودکار تغییر وضعیت
• کاهش تعداد استعلام‌های API
• ثبت تاریخچه هر پیام
• شناسایی سریع خطاها
• هماهنگی میان پنل پیامکی و CRM
• امکان اجرای عملیات خودکار
• بهبود گزارش‌های مدیریتی
• کاهش فشار روی زیرساخت نرم‌افزار

بااین‌حال اصطلاح «لحظه‌ای» نباید به معنای دریافت بدون تأخیر تفسیر شود. ممکن است اپراتور گزارش تحویل را چند ثانیه یا حتی چند دقیقه بعد برگرداند. خاموش‌بودن گوشی، اختلال شبکه و نوع مسیر ارسال نیز می‌توانند این زمان را افزایش دهند.

محدودیت ها و اشتباهات رایج

یکی‌دانستن Sent و Delivered

وضعیت Sent معمولا نشان می‌دهد پیام به یکی از مراحل بعدی ارسال شده است. Delivered یعنی سامانه یا اپراتور تحویل پیام را گزارش کرده است. این دو وضعیت نباید در گزارش‌ها یکسان در نظر گرفته شوند.

اعتماد به هر درخواست ورودی

Webhook URL معمولا یک Endpoint عمومی است و ممکن است درخواست جعلی دریافت کند. در صورت پشتیبانی سرویس دهنده، باید Signature، Token ،Secret Header یا IPهای معتبر بررسی شوند. استفاده از HTTPS نیز ضروری است، اما HTTPS به‌تنهایی هویت فرستنده درخواست را اثبات نمی‌کند.

ذخیره نکردن Message ID

اگر شناسه پیام در زمان ارسال ذخیره نشود، گزارش برگشتی قابل اتصال به سفارش، کاربر یا عملیات اصلی نیست. ثبت شماره موبایل به‌تنهایی کافی نیست، زیرا ممکن است چند پیام در فاصله کوتاه برای یک شماره ارسال شده باشد.

پردازش چندباره یک Callback

اگر سامانه پیامکی پاسخ موفق دریافت نکند، ممکن است گزارش را دوباره ارسال کند. بنابراین Endpoint باید Idempotent باشد؛ یعنی پردازش چندباره یک رویداد، اثر تکراری ایجاد نکند. برای مثال، نباید دریافت دوباره یک Callback باعث ساخت چند تیکت یا ارسال چند پیام جایگزین شود.

پاسخ دیرهنگام

انجام پردازش سنگین داخل درخواست Webhook می‌تواند باعث Timeout شود. بهتر است Endpoint پس از اعتبارسنجی اولیه، اطلاعات را در دیتابیس یا صف ثبت کند و سریع پاسخ موفق برگرداند.

نداشتن مسیر بازیابی

اگر سرور هنگام ارسال Callback در دسترس نباشد، ممکن است گزارش ثبت نشود. سرویس‌دهنده باید Retry داشته باشد و نرم افزار شما نیز بهتر است پیام‌های بلاتکلیف را با یک Job دوره‌ای شناسایی کند.

پیاده سازی امن Webhook پیامک

پیش از فعال سازی Webhook این موارد را بررسی کنید:

1. Callback URL با HTTPS در دسترس باشد.
2. Message ID در زمان ارسال ذخیره شود.
3. اصالت درخواست بررسی شود.
4. داده ورودی اعتبارسنجی شود.
5. وضعیت‌ها به مدل داخلی استاندارد نگاشت شوند.
6. پردازش Callback تکراری اثر جانبی ایجاد نکند.
7. عملیات سنگین به Queue منتقل شود.
8. خطاهای ورودی و پاسخ‌ها Log شوند.
9. پیام‌های بلاتکلیف دوره‌ای استعلام شوند.
10. اطلاعات حساس در Log عمومی ثبت نشوند.
11. Retry سرویس‌دهنده بررسی شود.
12. دسترس پذیری Endpoint مانیتور شود.

Webhook چه زمانی مناسب است؟

• ارسال پیامک از سایت، اپلیکیشن یا CRM انجام می‌شود.
• وضعیت تحویل در فرایند کسب و کار اهمیت دارد.
• حجم پیام‌ها زیاد است.
• تیم پشتیبانی به تاریخچه دقیق نیاز دارد.
• بر اساس نتیجه ارسال، عملیات دیگری اجرا می‌شود.
• Polling تعداد زیادی درخواست غیرضروری تولید می‌کند.

در پروژه‌هایی که نیاز دارند اطلاعات ارسال مستقیما داخل نرم افزار ثبت شود، استفاده از وب‌سرویس پیامکی بهین زمانی منطقی است که مستندات فنی، وضعیت‌های قابل دریافت، ظرفیت API و نحوه ارسال گزارش پیش از اتصال بررسی شده باشند.

Webhook چه زمانی ضروری نیست؟

اگر پیامک ها به‌صورت محدود و دستی از پنل ارسال می‌شوند و گزارش داخل همان پنل برای کاربر کافی است، پیاده سازی Webhook ارزش فنی زیادی ایجاد نمی‌کند. همچنین در پروژه‌ای که وضعیت تحویل هیچ اثری بر عملیات بعدی ندارد، ساخت Endpoint، مانیتورینگ، امنیت و نگهداری آن ممکن است هزینه‌ای بیش از منفعتش داشته باشد. در چنین شرایطی، مشاهده گزارش داخل پنل یا استعلام محدود API می‌تواند کافی باشد.

Webhook پیامک مسیر برگشت وضعیت از سامانه پیامکی به نرم افزار است. API درخواست ارسال را منتقل می‌کند و Webhook نتیجه تغییر وضعیت را برمی‌گرداند. پیاده سازی درست این سازوکار فقط به ثبت یک URL محدود نمی‌شود. ذخیره Message ID، بررسی امنیت درخواست، کنترل رویدادهای تکراری، پاسخ سریع، نگاشت وضعیت‌ها و طراحی مسیر بازیابی گزارش‌های ازدست‌رفته از الزامات اصلی هستند.

برای ارسال های دستی، گزارش پنل معمولا کافی است؛ اما در فروشگاه‌های اینترنتی، CRMها، سامانه‌های OTP و نرم افزارهای سازمانی، Webhook می‌تواند مانیتورینگ و خودکارسازی فرایند پیامک را دقیق‌تر و قابل‌اعتمادتر کند.

اگر لازم است وضعیت پیامک های OTP، سفارش یا اطلاع‌رسانی مستقیما در سایت یا CRM ثبت شود، پیش از اتصال باید ساختار API، نوع گزارش تحویل و حجم درخواست‌ها بررسی شود. می‌توانند برای انتخاب پنل و روش یکپارچه سازی مناسب با کارشناسان بهین اس ام اس تماس بگیرید.

سوالات متداول

Webhook پیامک چیست؟

Webhook پیامک آدرسی در نرم افزار شماست که سامانه پیامکی، تغییر وضعیت SMS مانند تحویل‌شدن یا ناموفق‌بودن را به‌صورت خودکار به آن ارسال می‌کند.

آیا Webhook تحویل پیامک را تضمین می‌کند؟

خیر. Webhook فقط وضعیت اعلام‌شده از سوی سامانه یا اپراتور را منتقل می‌کند و خود آن تضمین‌کننده تحویل پیام نیست.

تفاوت Callback و Delivery Report چیست؟

Delivery Report اطلاعات وضعیت پیام است؛ Callback یا Webhook روشی است که این اطلاعات را به نرم افزار شما منتقل می‌کند.

آیا می‌توان به‌جای Webhook از API استفاده کرد؟

بله. می‌توان وضعیت پیام را با API استعلام کرد، اما Polling مداوم درخواست‌های بیشتری تولید می‌کند. API معمولا مسیر پشتیبان مناسبی برای Webhook است.

برای دریافت گزارش لحظه ای پیامک چه چیزهایی لازم است؟

به Callback URL امن، ذخیره Message ID، اعتبارسنجی درخواست، نگاشت وضعیت‌ها، ثبت Log، کنترل رویداد تکراری و سازوکار بازیابی نیاز دارید.