Skip to Content
Quick Start

Quick Start

This guide gets you from zero to a working webhook endpoint using Node.js and Express.

Prerequisites

  • A SingleForm account with at least one form created at app.singleform.ai 
  • Node.js 18+ installed
  • Your webhook secret from Settings → Webhook Security in the SingleForm dashboard

Step 1: Set Up Your Project

mkdir my-webhook-server && cd my-webhook-server
npm init -y
npm install express @singleform/express-webhook

Step 2: Create Your Webhook Endpoint

Create a file called server.js:

import express from "express";
import { singleform } from "@singleform/express-webhook";
 
const app = express();
app.use(express.json());
 
app.post(
  "/webhooks/singleform",
  singleform({ secret: process.env.SINGLEFORM_SECRET }),
  (req, res) => {
    const { formId } = req.singleform;
    const { email, firstName, lastName } = req.body;
 
    console.log(`New submission for form ${formId}:`);
    console.log({ email, firstName, lastName });
 
    // Your business logic here:
    // - Save to database
    // - Send confirmation email
    // - Update CRM
    // - etc.
 
    res.singleformSuccess({
      submissionId: "12345",
      message: "Thank you for your submission!",
    });
  }
);
 
app.listen(3000, () => {
  console.log("Webhook server running on port 3000");
});

Step 3: Set Your Environment Variable

export SINGLEFORM_SECRET="sf_secret_your_secret_here"

Get your secret from the SingleForm dashboard: Settings → Webhook Security → Generate Secret.

Step 4: Start Your Server

node server.js

Step 5: Configure SingleForm

  1. Go to app.singleform.ai 
  2. Open your form’s settings
  3. Set your webhook URL (e.g., https://your-server.com/webhooks/singleform)
  4. Select Custom API as the webhook type
  5. If you’re using the embed script on your website, verify your domain in Settings → Domain Verification

Step 6: Test It

Submit a test form from the SingleForm mobile app. You should see the submission data logged in your terminal.

What Happens Under the Hood

  1. A user fills out and submits a form in the SingleForm mobile app
  2. The SingleForm API signs the request using HMAC-SHA256 with your webhook secret
  3. Your endpoint receives a POST request with 4 signed headers
  4. The singleform() middleware automatically verifies the signature, timestamp, and nonce
  5. Your handler function receives the verified submission data in req.body
  6. Your response is relayed back to the mobile app and displayed to the user

Next Steps

Webhook Form ExampleEmbed Script