=formuljar=

a simple web form with extra security

🚀 Features

Google reCaptcha v3 (server-side verification) 🥊
Integration with Telegram (notifications) 🎱
Integration with Google Spreadsheets (audit) 🧩
Integration with your CRM (coming soon...) 💹
Support for referral/affiliate links 🤑
Serverless framework on AWS: API GW, Lambda, SQS, S3, Cloudfront ❤️

🍭 Demo

Prod: https://formuljar.maslick.tech
Test: https://formuljar-test.maslick.tech

💡 Motivation

Often times businesses need a simple static web form to get user feedback and/or generate sales leads, so that customers fill out a web form with their contact data. The business then needs to get a notification (e.g. via Telegram) and store customer info in a document (e.g. Google Spreadsheets).

The integration part with 3rd party services is pretty much straightforward. However, several challenges may arise:

1️⃣ Your backend server may be overloaded 🙅 by a number of automated requests 💣

An attacker 🕵️‍♂️ (e.g. your competitor) may get the form handler URL and issue a number of dummy POST requests, thus making your backend send a lot of notifications and polluting your spreadsheet with fake data. Here we can use reCaptcha to process only the requests produced by a human.

2️⃣ You may need to process requests asynchronously 🏓 and respond immediately! 🏇

You don't want your users to wait! Integration with 3rd party services such as Telegram, Spreadsheets, etc. may take some time, so you need to decouple the web request and business logic by using a message queue (e.g. AWS SQS).

3️⃣ Your solution should scale well 📡

Hosting on Heroku for $7/month is a good option, but it doesn't scale well. Better use Serverless on AWS with almost infinite scaling capabilities.

4️⃣ Your solution should be cheap! 💸

You could host your app on Heroku. There are 2 options here: a free plan (limited availability, no custom domain, no TLS) or a Hobby plan ($7 per dyno per month). However, there is a better hosting solution which is almost free, and that is - AWS 👌

✅ Installation

♠️ reCaptcha

Go to https://www.google.com/recaptcha/admin and create a new site.
Go over to Settings and copy both CAPTCHA_PUBLIC and CAPTCHA_SECRET.
Add necessary domains where you want to use reCaptcha (e.g. d2dc90ktgsfnzk.cloudfront.net, localhost, formuljar.maslick.ru).

♥️ Telegram

Send a new message to @BotFather: /newbot.
Give your bot a name (e.g. Formuljar).
Choose a username for your bot (e.g. formuljar_bot).
You will get a TELEGRAM_BOT_TOKEN (e.g. 1234567890:ABCdefgHijklmnoPQrsTUVwXyZ).
You can also set a profile pic by issuing /setuserpic.
Create a channel. Set its type to private and invite your bot (e.g. @formuljar_bot) as admin 👩‍💼 with the ability to post messages.
Start a conversation with @getidsbot.
Write a sample message into your channel and forward it to @getidsbot.
Switch to @getidsbot and find your TELEGRAM_CHAT_ID (Origin chat -> id): e.g. -1001375717457.

♣️ Google Spreadsheets

Log in to GCP console https://console.cloud.google.com/
Create a new project.
Enable Google Sheets API.
Click Manage and head over to Credentials. Create a new service account.
Create a new API key. Download the JSON. Copy the JSON into the GOOGLE_CREDENTIALS env. variable.
Create a new Spreadsheet and Share the document with your service account email (see JSON -> client_email).
Get the id of your document (e.g. https://docs.google.com/spreadsheets/d/1JnW6kWGL-Xily71-xxxxxx-Bw_lfW2Lb_SyCjx3uBTyQ -> 1JnW6kWGL-Xily71-xxxxxx-Bw_lfW2Lb_SyCjx3uBTyQ). This will be your SPREADSHEET_ID env. variable.

♦️ Serverless

$ export CAPTCHA_PUBLIC=...
$ export CAPTCHA_SECRET=...
$ export TELEGRAM_CHAT_ID=...
$ export TELEGRAM_BOT_TOKEN=
$ export GOOGLE_CREDENTIALS=...
$ export SPREADSHEET_ID=...
$ export SHEET_NAME=...

$ npm i -g serverless
$ sls config credentials --provider aws --key <key-id> --secret <secret>
$ sls deploy --stage prod --verbose

maslick / formuljar