فنی · پاسخ مستند
وبهوک ایمیل چیست؟ تعریف و پیاده‌سازی فنی
وبهوک ایمیل یک callback از نوع HTTP است که ارائهدهنده خدمات ایمیل آن را فعال می‌کند تا یک سرور مقصد را از رویدادهای مشخص مطلع کند. به‌جای اینکه برنامه برای دریافت وضعیت مرتب یک API را بررسی (poll) کند، ارائهدهنده بلافاصله پس از وقوع رویدادی مانند شکست تحویل یا کلیک روی لینک، یک payload از نوع JSON یا XML را به یک URL ازپیش‌تعریف‌شده ارسال می‌کند.
سازوکار عملکرد
وقتی رویدادی رخ می‌دهد، ارائهدهنده ایمیل یک درخواست HTTP POST ایجاد می‌کند. این درخواست حاوی payload با متادیتای رویداد است، از جمله شناسه پیام، نشانی گیرنده و زمان وقوع. سرور گیرنده باید روی یک endpoint عمومی گوش دهد، درخواست ورودی را اعتبارسنجی کند و برای اعلام دریافت، پاسخ 200 OK برگرداند. اگر سرور خطا برگرداند، ارائهدهنده ممکن است با راهبرد exponential backoff ارسال را دوباره تلاش کند.
اهمیت برای فرستندگان
وب‌هوک‌ها برای حفظ اعتبار فرستنده حیاتی‌اند. توسعه‌دهندگان با دریافت اعلان‌های بلادرنگ درباره برگشت‌های دائمی یا گزارش‌های اسپم، می‌توانند نشانی‌های نامعتبر را خودکار از فهرست‌های خود حذف کنند. این کار مانع ارسال مکرر به صندوق‌های ایمیل مرده میشود؛ یکی از اصلی‌ترین سیگنال‌هایی که ISPها برای تشخیص فرستندگان بی‌کیفیت استفاده میکنند. واکنش سریع به این سیگنال‌ها نرخ کلی تحویل‌پذیری را بالاتر می‌برد.
ملاحظات عملیاتی
خطاهای رایج شامل خطاهای timeout است، زمانی که سرور گیرنده payload را به‌صورت همگام (synchronous) پردازش می‌کند. برای جلوگیری از این مشکل، توسعه‌دهندگان باید معماری ناهمگامی پیاده کنند که در آن وبهوک دریافت میشود، در سیستمی مانند Redis یا RabbitMQ در صف قرار می‌گیرد و بلافاصله دریافت آن اعلام میشود. علاوه بر این، امنیت اهمیت بسیار بالایی دارد؛ سرورها باید امضای ارائهدهنده را تأیید کنند یا IP مبدأ را بررسی کنند تا اعلان‌های رویداد جعلی پذیرفته نشوند.
نمونه عملی پیاده‌سازی
یک گردش‌کار معمول شامل پیکربندی یک URL در ارائه‌دهنده‌ای مانند Resend یا Amazon SES است. وقتی کاربری روی لینکی در ایمیل کلیک می‌کند، ارائهدهنده یک درخواست POST به /webhooks/email با بدنه‌ای مانند { event: click, email: user@example.com, link: https://site.com/offer } ارسال می‌کند. سپس برنامه رکورد کاربر را در پایگاه داده به‌روز می‌کند تا کمپین موفق علامت بخورد.
یکپارچه‌سازی با ابزارها
راه‌اندازی وب‌هوک‌ها به یک URL عمومی و روشی برای آزمایش payloadها نیاز دارد. توسعه‌دهندگان می‌توانند از SendHQ یا ابزارهای رایگان آن (https://sendhq.cc/tools) برای مدیریت الزامات فنی زیرساخت ایمیل خود و اطمینان از هم‌خوانی پیکربندی با استانداردهای صنعت کمک بگیرند.
پرسش‌هایی که تیم‌ها می‌پرسند
تفاوت API و وبهوک چیست؟
API درخواستی است که کلاینت برای دریافت (pull) داده به سرور می‌فرستد. وبهوک درخواستی است که سرور هنگام وقوع یک رویداد، برای ارسال خودکار (push) داده به کلاینت می‌فرستد.
چگونه endpoint وبهوک ایمیل را امن کنم؟
از توکنهای مخفی در هدر استفاده کنید، امضای HMAC ارائهشده توسط سرویس ایمیل را تأیید کنید یا ترافیک ورودی را به بازههای IP مشخص متعلق به ارائهدهنده محدود کنید.
اگر هنگام رویداد وبهوک سرور من از دسترس خارج باشد چه میشود؟
بیشتر ارائهدهندگان حرفهای رویداد را در صف نگه میدارند و پیش از اینکه آن را غیرقابلتحویل علامت بزنند، چندین بار در طول چند ساعت یا چند روز برای تحویل مجدد تلاش میکنند.
منابع اصلی
- مستندات Resend — Resend
- مستندات توسعه‌دهندگان Postmark — Postmark
- راهنمای توسعه‌دهندگان Amazon SES — Amazon Web Services