وب هوک (webhook)
مقدمه
وب هوک (webhook) ابزاری است که امکان ارسال انواع اطلاعات به آدرس دلخواهی که توسط مقصد مشخص شده است را در موقع فراخوانی یک رویداد (event) در مبدا، محیا می‌کند.
نکته
می‌توان برای مدیریت و حفظ امنیت درگاه ورودی از توکن احراز هویت (authentication token) نیز استفاده کرد.
اضافه کردن webhook
برای ساخت وب هوک (webhook) ابتدا باید وارد لندین شده، سپس وارد صفحه مدیریت لید و در نهایت با انتخاب یکی از صفحات، وارد تنظیمات آن شده و در این صفحه می‌توان تنظیمات وب هوک (webhook) مربوط به صفحه لندینگ پیج خود را مشاهده کنید.
حال برای تنظیم آدرس جدید مراحل زیر را طی کنید:
- از فعال بودن web application خود در آدرس مربوطه اطمینان حاصل کنید.
- آدرس متصل به web application خود را وارد کنید.
- در صورت تمایل توکن احراز هویت (authentication token) را برای آدرس مربوطه وارد کنید.
- بر روی دکمه ثبت کلیک کرده و پیام‌های دریافتی را دنبال کنید.
توجه
در صورت ذخیره آدرس و تنظیمات مربوط به آن، امکان تغییر آن وجود ندارد و فقط حذف آن امکان پذیر است.
احتیاط
در صورت فعال نبودن آدرس مربوطه، درخواست‌‌های ارسال شده مجدد ارسال نمی‌شود !
خطر
استفاده از توکن احراز هویتی (authentication token) که با گذر زمان منقضی می‌شود، امکان پذیر نیست و بعد از انقضای توکن (token) هیچ درخواستی به مقصد ارسال نخواهد شد !
ساختار Request
درخواست ارسالی از سمت سرور‌های لندین در قالب HTTP با متد POST ارسال خواهد شد.
ساختار header در ادامه آمده است:
accept: "application/json"
content-type: "application/json"
cache-control: "no-cache"
Authorization: "xxxxxxxxxxxxxxxxxxxxxxx"
توجه
هدر Authorization وقتی تنظیم می‌شود که شما توکن احراز هویت (authentication token) را برای این آدرس ثبت کرده باشید.
در قسمت body اطلاعات لید قرار دارد که ساختار آن در ادامه آورده شده است:
{
"landing_id": "xxxxxxxxxxxxxxxxxxxxxx",
"lead_capture_slug": "leadcapture",
"lead_capture_fields": [
{
"key": "نام و نام خانوادگی",
"value": "amir aghayi",
"type": "text"
},
{
"key": "شماره تماس",
"value": "09130000000",
"type": "phone_number"
},
{
"key": "آدرس ایمیل",
"value": "document@landin.ir",
"type": "email_address"
}
],
"utm_params": {
"source": "direct",
"medium": "none",
"campaign": "",
"content": "",
"term": ""
}
}
نکته
صفت lead_capture_slug در واقع بیانگر شناسه تغییر پذیر فرم جمع آوری لید می‌باشد که می‌توان از طریق آن منبع داده دریافتی را تشخیص داد. صفت lead_capture_fields بیانگر مقادیر ورودی است که از کاربر دریافت شده است و شامل ۳ صفت key، value و type است که صفت type فقط می‌تواند شامل یکی از عبارت‌های text، phone_number و email_address باشد.
ساختار Response
سرور‌های مقصد در جواب درخواست ارسال شده از سرور‌های لندین باید جوابی مبنی بر دریافت داده برگردانند. برای این منظور نیاز است در صورت تایید و دریافت اطلاعات، در status code مقدار 200 را قرار دهید.
توجه
در صورت تنظیم status code به 200 نیازی به ارسال body نیست.
در صورتی که به هر دلیلی مشکل پیش بینی شده‌ای در سرور وجود داشته باشد می‌توانید علاوه بر تنظیم status code مورد نظر، در body مطابق ساختار زیر مشکل مربوطه را نیز گزارش دهید:
{
"error_message": "a error occured in web application"
}
توجه
در صورتی که status code چیزی غیر از 200 باشد، بیانگر خطا بوده و لینک مربوطه غیر فعال شده و برای شما ایمیلی حاوی گزارش خطا (درصورت تنظیم توسط شما) ارسال خواهد شد.
احتیاط
بعد از رفع مشکل گزارش شده، باید به داشبورد (dashboard) قسمت اتصالات webhook رفته و لینک غیر فعال شده را با زدن دکمه بررسی مجدد، فعال کنید. در غیر این صورت لید‌های جدید برای این آدرس ارسال نخواهد شد !