وبهوک فرم: پاسخها را لحظهای به سیستم خودتان بفرستید
بهجای اینکه هر روز اکسل بگیرید، بگذارید فرم هر بار که پاسخی میآید خودش به سامانهی شما خبر بدهد.
وبهوک یعنی وقتی اتفاقی میافتد (مثلاً پاسخ تازهای ثبت میشود)، سامانهی فرم یک درخواست HTTP به نشانیای که شما دادهاید میفرستد. برعکسِ حالت عادی که شما باید مرتب بپرسید «چیز جدیدی هست؟».
چه چیزی دریافت میکنید
معمولاً یک POST با بدنهی JSON که شامل شناسهی پاسخ، زمان ثبت، و مقدار هر فیلد با کلیدش است. کلید فیلد همان چیزی است که در فرمساز تعیین کردهاید — پس کلیدها را معنادار بگذارید (national_id نه q7).
سه چیزی که حتماً باید پیاده کنید
۱. تأیید امضا
هر کسی که نشانی وبهوک شما را بداند میتواند دادهی جعلی بفرستد. سامانهی فرستنده معمولاً یک امضای رمزنگاریشده در هدر میگذارد که با کلید مشترک ساخته شده. شما باید همان امضا را محاسبه و مقایسه کنید و اگر نخواند، درخواست را رد کنید.
بدون این، وبهوک شما یک درِ باز است.
۲. پاسخ سریع بدهید
وبهوک باید در چند ثانیه 200 برگرداند. اگر کار سنگینی دارید (ارسال ایمیل، بهروزرسانی چند سیستم)، اول 200 بدهید و بعد کار را در صف پسزمینه انجام دهید.
اگر دیر جواب بدهید، فرستنده فکر میکند شکست خورده و دوباره میفرستد — و شما یک پاسخ را دو بار پردازش میکنید.
۳. تکراری را تشخیص بدهید
وبهوکها «حداقل یک بار» تحویل داده میشوند، نه «دقیقاً یک بار». یعنی ممکن است یک رویداد دو بار برسد. شناسهی پاسخ را ذخیره کنید و اگر تکراری بود، نادیده بگیرید.
این نکتهای است که معمولاً فراموش میشود و بعد در سیستم مالی دو بار فاکتور صادر میشود.
تلاش مجدد و شکست
اگر سرور شما خواب باشد، سامانهی فرستنده معمولاً چند بار با فاصلهی فزاینده تلاش میکند. ولی بالاخره تسلیم میشود.
برای همین، وبهوک نباید تنها راه دریافت داده باشد. یک فرایند پشتیبان داشته باشید که مثلاً شبانه پاسخهای روز را از API بگیرد و با آنچه دریافت کرده مقایسه کند.
در محیط توسعه چطور تستش کنید
سرور محلی شما از اینترنت قابل دسترس نیست. ابزارهایی هستند که یک نشانی عمومی موقت میسازند و به پورت محلی شما تونل میزنند. برای تست اولیه هم میتوانید از سرویسهایی استفاده کنید که درخواست را نمایش میدهند تا شکل داده را ببینید.