Getting Started
This guide covers the end-to-end process of integrating Forge: creating a form endpoint, embedding it in your frontend, and processing submissions via webhooks.
What is Forge?
Forge is headless infrastructure for form management. We handle the ingestion, validation, storage, and delivery of form data so you don't have to build a backend for every input field.
Unlike form builders, we do not impose UI constraints. You build the frontend in HTML, React, or Vue; we provide the API endpoint to receive the data and the webhooks to deliver it to your systems.
Prerequisites
- A Forge account (sign up at forge.dev).
- A frontend environment (static HTML file or a JS framework).
- A backend server or serverless function capable of receiving `POST` requests (for webhook processing).
1. Create a Form
You can create a form via the Dashboard or the CLI. For this guide, we will use the CLI to generate a new endpoint.
# Install the Forge CLI
npm install -g @forge/cli
# Login to your account
forge login
# Create a new form endpoint
forge form:create "Contact Us"The CLI will return a unique Form ID.
2. Embed the Form
Use standard HTML form tags. Set theaction attribute to the Forge ingestion URL.
<form action="https://api.forge.dev/f/f_12345abcde" method="POST">
<label for="email">Email</label>
<input type="email" name="email" required />
<label for="message">Message</label>
<textarea name="message" required></textarea>
<button type="submit">Send</button>
</form>React Users: You may prefer our React SDKfor handling loading states and optimistic UI updates without page reloads.
3. Receive Submissions
Forge delivers submissions to your backend via webhooks. Configure your webhook URL in the dashboard settings. Below is an example using Node.js and Express.
const express = require('express');
const app = express();
// Forge sends JSON payloads
app.use(express.json());
app.post('/webhooks/forge', (req, res) => {
const submission = req.body;
console.log('New submission:', submission.data.email);
// Process data (e.g., save to DB, send Slack alert)
// ALWAYS return 200 OK to acknowledge receipt
res.status(200).send('Received');
});Important: Forge expects a 200-299 status code. Any other status code (or a timeout) will trigger the retry mechanism.
Failure Handling
Forge is designed for high reliability. If your server is down or returns an error, we do not drop the data.
- Automatic Retries: We attempt delivery with an exponential backoff strategy (up to 72 hours).
- Dead Letter Queue (DLQ): If all retries fail, the event is moved to the DLQ. You can view these events in the dashboard.
- Replay: Once you fix your server issue, you can trigger a replay of DLQ events to process them again.