Webhooks Guide

What are FormBold Webhooks?

A webhook is an automated notification sent from FormBold to your server whenever a new form submission is recorded. Instead of constantly polling an API to check for new entries, FormBold instantly pushes an HTTP POST request containing the submission payload to your designated webhook URL.

Generating Personal Access Tokens

To authenticate API requests and verify webhook interactions, you will need an API Personal Access Token:

1. In your FormBold account, navigate to Account Settings > API Tokens.
2. Click 'Generate New Token'.
3. Give your token a descriptive name (e.g. 'Production Backend Webhook').
4. Click 'Create'. Copy and safely store the generated token — you will not be able to view it again.

Enabling HTTP API on Your Form

Before webhooks or API requests can interact with a specific form, ensure HTTP API Access is enabled:

• Open your form and go to Settings.
• Scroll to the 'Webhooks and HTTP API' section.
• Toggle ON 'Enable HTTP API'.

Webhook Event Payload Structure

When a visitor submits your form, FormBold sends an HTTP POST request with Content-Type: application/json containing this payload structure:

{
  "event": "submission.created",
  "form_id": "YOUR_FORM_ID",
  "submission_id": "sub_8f2b1a9c3d4e",
  "created_at": "2026-09-10T12:00:00.000Z",
  "data": {
    "name": "Sarah Connor",
    "email": "[email protected]",
    "message": "Interested in your enterprise solution.",
    "budget": "$10,000+"
  },
  "files": [],
  "is_spam": false
}

Handling Webhooks in Node.js / Express

Here is a sample Express.js endpoint ready to receive and process FormBold webhook events:

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/formbold-webhook", (req, res) => {
  const { event, form_id, data, created_at } = req.body;

  console.log(`[FormBold Webhook]: Received ${event} for form ${form_id}`);
  console.log("Submitter:", data.name, data.email);

  // Process data (e.g., save to custom database, trigger email, alert team)

  // Respond with 200 OK to acknowledge receipt
  return res.status(200).json({ received: true });
});

app.listen(3000, () => console.log("Webhook server running on port 3000"));

Testing Webhooks Locally

During development, you can test webhooks on your local machine using tools like ngrok:

1. Run your local server (e.g. on port 3000).
2. Expose your port using ngrok: ngrok http 3000
3. Copy the generated https forwarding URL (e.g. https://abc123.ngrok-free.app/api/formbold-webhook).
4. Paste this URL into the Webhook URL field in your FormBold form Integrations tab.
5. Submit your frontend form and observe the live incoming payload in your terminal console!