Monitoring HeyForm with Vigilmon

HeyForm gives you a privacy-respecting, self-hosted alternative to Typeform and Google Forms — conversational forms with conditional logic, file uploads, and webhook integrations, running entirely on your infrastructure. But self-hosting means you own the reliability. A MongoDB connection failure breaks form submissions while your form pages continue loading. A downed Go API server makes embedded forms silently fail on your clients' websites. An expired SSL certificate drops completion rates by showing browser security warnings to respondents. Vigilmon watches your HeyForm deployment across all these failure modes so you never silently lose a survey response or a lead registration.

What You'll Set Up

• HeyForm API server health monitor (Go backend)
• Web application availability monitor (frontend dashboard)
• MongoDB connectivity check via login page behavior
• SSL certificate expiry alerts
• Heartbeat monitor for the form submission pipeline

Prerequisites

• HeyForm deployed via Docker Compose with the Go API server accessible (port 8000 by default, or via reverse proxy)
• A free Vigilmon account

Step 1: Monitor the HeyForm API Server

The Go API server is the core of HeyForm — it handles form definitions, submissions, webhooks, and integrations. A dedicated health endpoint makes this straightforward to monitor.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the API server URL: http://yourserver:8000/health (or https://heyform.yourdomain.com/health if using a reverse proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter ok or status.
7. Click Save.

If the Go binary crashes or its container exits, this monitor fires within one minute — before any form respondent encounters a broken submission.

Step 2: Monitor the HeyForm Web Application

The web dashboard (React frontend) is served via nginx or the reverse proxy in front of the Go API. A 200 response with the HeyForm branding confirms the frontend is being served and the routing layer is healthy.

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your HeyForm domain: https://heyform.yourdomain.com.
4. Set Expected HTTP status to 200.
5. Under Keyword check, enter HeyForm.
6. Click Save.

If you've customized the HeyForm deployment with your own branding, use a keyword from your own page title instead.

Step 3: Monitor MongoDB Connectivity

HeyForm stores all form definitions, responses, and user accounts in MongoDB. The login page loads user count and session data from MongoDB on render — a 500 error or a "Database connection error" message instead of the login form is a reliable signal that MongoDB is unavailable.

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: https://heyform.yourdomain.com (the root or login page).
4. Set Expected HTTP status to 200.
5. Under Keyword check, enter HeyForm — this confirms a real rendered page, not a database error page.
6. Under Negative keyword check (if available), enter Database connection error.
7. Click Save.

This monitor catches the most common failure mode in Docker Compose HeyForm deployments: the Go container starts before MongoDB is ready, or MongoDB runs out of disk space and stops accepting writes.

Step 4: SSL Certificate Alerts

HeyForm forms frequently collect personally identifiable information — contact details, survey responses, registration data. HTTPS is mandatory. An expired certificate shows a full-page browser security warning to every form respondent, dropping completion rates to near zero and making your embedded forms appear broken to clients.

1. Open the web application monitor created in Step 2.
2. Scroll to the SSL certificate section.
3. Enable Monitor SSL certificate.
4. Set Alert when certificate expires in less than 21 days.
5. Click Save.

Check that your reverse proxy (nginx, Caddy, or Traefik) is handling Let's Encrypt renewal automatically. Caddy renews certificates without configuration; nginx requires a Certbot cron job. Either way, verify the renewal path is working before your first certificate expires:

sudo certbot renew --dry-run
# or for Caddy: caddy reload

Step 5: Heartbeat Monitoring for the Form Submission Pipeline

The Go API server can be running and returning 200 on /health while the submission pipeline is broken. MongoDB write failures, webhook delivery failures, and Redis cache issues can all cause form submissions to silently fail after the user clicks Submit. The form respondent sees a generic success message; you never see the response.

Use a heartbeat monitor to run an hourly submission pipeline test:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set Expected ping interval to 60 minutes.
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_TOKEN.

Create a dedicated heartbeat test form in HeyForm (a simple single-field form — name it "Heartbeat Test" and note its form ID). Then write a test script:

#!/bin/bash
set -e

HEYFORM_URL="https://heyform.yourdomain.com"
HEARTBEAT_FORM_ID="YOUR_FORM_ID"  # The public ID of your test form
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_TOKEN"

# Submit a test response to the heartbeat form
RESPONSE=$(curl -sf -X POST \
  "$HEYFORM_URL/api/form/$HEARTBEAT_FORM_ID/submit" \
  -H "Content-Type: application/json" \
  -d '{"fields": [{"kind": "short_text", "value": "heartbeat-test"}]}')

# Verify the response indicates success
echo "$RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); assert d.get('code') == 0, 'Submission failed'"

# Signal success to Vigilmon
curl -sf "$HEARTBEAT_URL"

Schedule with cron:

0 * * * * /path/to/heyform-submission-test.sh >> /var/log/heyform-heartbeat.log 2>&1

This end-to-end test exercises the full path: Go API → MongoDB write → optional webhook trigger. If any component in that chain fails, the script errors and Vigilmon never receives its ping.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
2. For the API server and web app monitors, set Consecutive failures before alert to 2 — Docker container restarts during updates take a few seconds and should not trigger a false alarm.
3. For the SSL certificate monitor, set Alert immediately — an expiring certificate has a fixed countdown that needs action, not confirmation.

Summary

| Monitor | Target | What It Catches | |---|---|---| | API server | :8000/health | Go server crash, container exit | | Web application | https://heyform.yourdomain.com | Frontend/proxy failure | | MongoDB check | Login page + keyword | MongoDB down, disk full | | SSL certificate | HeyForm domain | Let's Encrypt renewal failure | | Submission heartbeat | Hourly cron → Vigilmon | Broken submission pipeline, MongoDB write failure |

HeyForm's self-hosted model keeps your survey data private and off third-party servers — Vigilmon ensures your forms are actually collecting the responses you're sending them to capture. With Go API health checks, MongoDB connectivity verification, and hourly submission pipeline tests, you get the full observability picture for a production form infrastructure.