Integration Examples

SingleForm webhooks work with any server that can receive HTTP POST requests. Below are complete examples showing manual signature verification for Node.js, Python, Ruby, and PHP.

These examples show manual verification. If you’d rather skip the boilerplate, use one of our official middleware libraries for Express, Flask, Django, FastAPI, Rails, or Sinatra.

Full Examples

Node.js (SDK)


// Using the official @singleform/express-webhook middleware
// Install: npm install express @singleform/express-webhook
 
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(`Form: ${formId}`);
    console.log("Data:", { email, firstName, lastName });
 
    // Your business logic here
    // - Save to database
    // - Send email
    // - Update CRM
 
    res.singleformSuccess({
      submissionId: "12345",
      message: "Thank you for your submission!",
    });
  }
);
 
app.listen(3000, () => console.log("Webhook server running on port 3000"));

Node.js (Manual)


// Manual verification without the SDK
import express from "express";
import crypto from "crypto";
 
const app = express();
app.use(express.json());
 
app.post("/webhooks/singleform", (req, res) => {
  const signature = req.headers["x-singleform-signature"];
  const timestamp = req.headers["x-singleform-timestamp"];
  const nonce = req.headers["x-singleform-nonce"];
  const formId = req.headers["x-singleform-form-id"];
 
  // Check all headers are present
  if (!signature || !timestamp || !nonce || !formId) {
    return res.status(401).json({
      success: false,
      error: { type: "MISSING_HEADERS", message: "Missing required headers" },
    });
  }
 
  // Check timestamp is within 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return res.status(401).json({
      success: false,
      error: { type: "TIMESTAMP_EXPIRED", message: "Request too old" },
    });
  }
 
  // Compute expected signature
  const payload = `${formId}.${timestamp}.${nonce}`;
  const expected = crypto
    .createHmac("sha256", process.env.SINGLEFORM_SECRET)
    .update(payload)
    .digest("hex");
 
  // Timing-safe comparison
  let isValid = false;
  try {
    isValid = crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  } catch {
    isValid = false;
  }
 
  if (!isValid) {
    return res.status(401).json({
      success: false,
      error: { type: "SIGNATURE_MISMATCH", message: "Invalid signature" },
    });
  }
 
  // Signature verified — process the submission
  const { email, firstName, lastName } = req.body;
 
  console.log(`Form: ${formId}`);
  console.log("Data:", { email, firstName, lastName });
 
  res.json({ success: true, data: { submissionId: "12345" } });
});
 
app.listen(3000, () => console.log("Webhook server running on port 3000"));

Python (Flask)


# Flask example
# Install: pip install flask
 
from flask import Flask, request, jsonify
import hmac
import hashlib
import time
import os
 
app = Flask(__name__)
WEBHOOK_SECRET = os.getenv('SINGLEFORM_SECRET')
 
@app.route('/webhooks/singleform', methods=['POST'])
def webhook():
    # Extract headers
    signature = request.headers.get('X-SingleForm-Signature')
    timestamp = request.headers.get('X-SingleForm-Timestamp')
    nonce = request.headers.get('X-SingleForm-Nonce')
    form_id = request.headers.get('X-SingleForm-Form-Id')
 
    # Verify all headers are present
    if not all([signature, timestamp, nonce, form_id]):
        return jsonify({
            'success': False,
            'error': {'type': 'MISSING_HEADERS', 'message': 'Missing required headers'}
        }), 401
 
    # Verify signature
    if not verify_signature(form_id, timestamp, nonce, signature):
        return jsonify({
            'success': False,
            'error': {'type': 'SIGNATURE_MISMATCH', 'message': 'Invalid signature'}
        }), 401
 
    # Process the submission
    data = request.json
    print(f"Form: {form_id}")
    print(f"Data: {data}")
 
    # Your business logic here
    # - Save to database
    # - Send email
    # - Update CRM
 
    return jsonify({
        'success': True,
        'data': {
            'submissionId': '12345',
            'message': 'Thank you for your submission!'
        }
    })
 
def verify_signature(form_id, timestamp, nonce, signature):
    # Check timestamp is within 5 minutes
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False
 
    # Compute expected signature
    payload = f"{form_id}.{timestamp}.{nonce}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
 
    # Timing-safe comparison
    return hmac.compare_digest(signature, expected)
 
if __name__ == '__main__':
    app.run(port=3000)

Ruby (Sinatra)


# Sinatra example
# Install: gem install sinatra
 
require "sinatra"
require "json"
require "openssl"
 
WEBHOOK_SECRET = ENV["SINGLEFORM_SECRET"]
 
post "/webhooks/singleform" do
  # Extract headers
  signature = request.env["HTTP_X_SINGLEFORM_SIGNATURE"]
  timestamp = request.env["HTTP_X_SINGLEFORM_TIMESTAMP"]
  nonce     = request.env["HTTP_X_SINGLEFORM_NONCE"]
  form_id   = request.env["HTTP_X_SINGLEFORM_FORM_ID"]
 
  # Verify all headers are present
  unless [signature, timestamp, nonce, form_id].all? { |h| h && !h.empty? }
    halt 401, { "Content-Type" => "application/json" },
      JSON.generate({
        success: false,
        error: { type: "MISSING_HEADERS", message: "Missing required headers" }
      })
  end
 
  # Verify signature
  unless verify_signature(form_id, timestamp, nonce, signature)
    halt 401, { "Content-Type" => "application/json" },
      JSON.generate({
        success: false,
        error: { type: "SIGNATURE_MISMATCH", message: "Invalid signature" }
      })
  end
 
  # Process the submission
  data = JSON.parse(request.body.read)
  puts "Form: #{form_id}"
  puts "Data: #{data}"
 
  # Your business logic here
  # - Save to database
  # - Send email
  # - Update CRM
 
  content_type :json
  JSON.generate({
    success: true,
    data: { submissionId: "12345", message: "Thank you for your submission!" }
  })
end
 
def verify_signature(form_id, timestamp, nonce, signature)
  # Check timestamp is within 5 minutes
  now = Time.now.to_i
  return false if (now - timestamp.to_i).abs > 300
 
  # Compute expected signature
  payload = "#{form_id}.#{timestamp}.#{nonce}"
  expected = OpenSSL::HMAC.hexdigest("SHA256", WEBHOOK_SECRET, payload)
 
  # Timing-safe comparison
  Rack::Utils.secure_compare(expected, signature)
end

PHP


<?php
// PHP example
 
$webhookSecret = getenv('SINGLEFORM_SECRET');
 
// Extract headers
$signature = $_SERVER['HTTP_X_SINGLEFORM_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_SINGLEFORM_TIMESTAMP'] ?? '';
$nonce     = $_SERVER['HTTP_X_SINGLEFORM_NONCE'] ?? '';
$formId    = $_SERVER['HTTP_X_SINGLEFORM_FORM_ID'] ?? '';
 
// Verify all headers are present
if (!$signature || !$timestamp || !$nonce || !$formId) {
    http_response_code(401);
    echo json_encode([
        'success' => false,
        'error' => ['type' => 'MISSING_HEADERS', 'message' => 'Missing required headers']
    ]);
    exit;
}
 
// Verify signature
if (!verifySignature($formId, $timestamp, $nonce, $signature, $webhookSecret)) {
    http_response_code(401);
    echo json_encode([
        'success' => false,
        'error' => ['type' => 'SIGNATURE_MISMATCH', 'message' => 'Invalid signature']
    ]);
    exit;
}
 
// Process the submission
$data = json_decode(file_get_contents('php://input'), true);
 
error_log("Form: $formId");
error_log("Data: " . json_encode($data));
 
// Your business logic here
// - Save to database
// - Send email
// - Update CRM
 
echo json_encode([
    'success' => true,
    'data' => [
        'submissionId' => '12345',
        'message' => 'Thank you for your submission!'
    ]
]);
 
function verifySignature($formId, $timestamp, $nonce, $signature, $secret) {
    // Check timestamp is within 5 minutes
    $now = time();
    if (abs($now - intval($timestamp)) > 300) {
        return false;
    }
 
    // Compute expected signature
    $payload = "$formId.$timestamp.$nonce";
    $expected = hash_hmac('sha256', $payload, $secret);
 
    // Timing-safe comparison
    return hash_equals($expected, $signature);
}
?>

Webhook Payload

Your endpoint receives a JSON POST body containing the form field values submitted by the user:


{
  "email": "jane@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+1234567890",
  "_meta": {
    "formId": "d4e5f6a7-b8c9-4d2e-a1f3-1234567890ab",
    "timestamp": "1706400000",
    "source": "singleform-mobile",
    "version": "1.0.0"
  }
}

The _meta object contains submission metadata. The timestamp is a Unix timestamp in seconds (as a string). The source indicates where the submission came from (singleform-mobile for app submissions, singleform-test for test webhooks). All other top-level keys are the form field values.

Environment Variables

Set your webhook secret as an environment variable on your server:


# Linux / macOS
export SINGLEFORM_SECRET="sf_secret_your_secret_here"
 
# Docker
docker run -e SINGLEFORM_SECRET="sf_secret_..." your-image
 
# .env file (use with dotenv or similar)
SINGLEFORM_SECRET=sf_secret_your_secret_here

Testing Your Integration

Use debug mode (Express SDK): Set debug: true to log each verification step
Check server logs: Look for the submission data after submitting a test form
Use the verifySignature helper for unit tests:


import { verifySignature } from "@singleform/express-webhook";
 
const isValid = verifySignature(
  "form-id-123",
  "1234567890",
  "nonce-abc",
  "computed-signature-hex",
  "sf_secret_your_secret"
);