Skip to main content

Integrations

Integrate FormLeap with your website, apps, and workflows using webhooks, embeds, API access, and AI-powered tools.

Overview

FormLeap offers multiple integration methods:

  • Webhooks - Real-time notifications when forms are submitted
  • Form Embedding - Add forms directly to your website
  • Reference Fields - Pass contextual data via URL parameters
  • API Access - Programmatic access to forms and submissions
  • AI Integration (MCP) - Create forms from PDFs or natural language

Webhooks

Webhooks let you receive real-time HTTP notifications when forms are submitted.

What are Webhooks?

When someone submits your form, FormLeap sends an HTTP POST request to a URL you specify with the submission data.

Use Cases:

  • Trigger automation workflows
  • Update your database
  • Send custom notifications
  • Integrate with third-party services
  • Process payments
  • Update CRM systems

Setting Up Webhooks

  1. Open your form in the builder
  2. Click Settings → Integrations
  3. Scroll to Webhooks
  4. Click Add Webhook
  5. Enter your webhook URL
  6. Select events to trigger on
  7. Click Save

Webhook URL:

  • Must be HTTPS (secure)
  • Must respond within 10 seconds
  • Should return 2xx status code

Example:

https://api.yourapp.com/webhooks/formleap

Webhook Events

Choose which events trigger webhook calls:

  • submission.created - New submission received
  • submission.updated - Submission modified (if allowed)
  • submission.deleted - Submission deleted

Most forms only need submission.created.

Webhook Payload

FormLeap sends a JSON payload with submission data:

{
  "event": "submission.created",
  "timestamp": "2025-01-20T10:30:00Z",
  "form": {
    "id": "form_123abc",
    "name": "Contact Form",
    "workspace_id": "ws_456def"
  },
  "submission": {
    "id": "sub_789ghi",
    "submitted_at": "2025-01-20T10:30:00Z",
    "status": "completed",
    "reference_data": {
      "article_id": "123",
      "source": "blog"
    },
    "responses": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Great service!"
    },
    "file_uploads": {
      "resume": [
        {
          "filename": "resume.pdf",
          "url": "https://files.formleap.app/...",
          "size": 102400,
          "content_type": "application/pdf"
        }
      ]
    }
  }
}

Key Fields:

  • event - Event type (e.g., submission.created)
  • form.id - Unique form identifier
  • submission.id - Unique submission identifier
  • submission.responses - All field values as key-value pairs
  • submission.reference_data - URL parameters you passed
  • file_uploads - Array of uploaded files with download URLs

Signature Verification

Available on: Pro, Business, and Enterprise plans

Verify webhook authenticity using HMAC signatures.

How it Works

FormLeap signs each webhook request with your webhook secret:

  1. You set a webhook secret in form settings
  2. FormLeap generates HMAC-SHA256 signature
  3. Signature sent in X-FormLeap-Signature header
  4. Your server verifies the signature

Setting a Webhook Secret

  1. Open Form Settings → Integrations → Webhooks
  2. Click Generate Secret or enter your own
  3. Save the secret securely (you won't see it again)
  4. Click Save

Verifying Signatures

Python Example:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    """Verify FormLeap webhook signature"""
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, f"sha256={expected}")

# In your webhook handler:
def handle_webhook(request):
    payload = request.body.decode('utf-8')
    signature = request.headers.get('X-FormLeap-Signature')
    secret = os.environ['FORMLEAP_WEBHOOK_SECRET']

    if not verify_webhook(payload, signature, secret):
        return 401  # Unauthorized

    # Process webhook
    data = json.loads(payload)
    # ...

Node.js Example:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

// In your webhook handler:
app.post('/webhooks/formleap', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-formleap-signature'];
  const secret = process.env.FORMLEAP_WEBHOOK_SECRET;

  if (!verifyWebhook(payload, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  const data = req.body;
  // ...

  res.status(200).send('OK');
});

Webhook Retries

If your endpoint returns an error (non-2xx status), FormLeap retries:

  • Retry 1: After 1 minute
  • Retry 2: After 5 minutes
  • Retry 3: After 15 minutes
  • Retry 4: After 1 hour
  • Retry 5: After 3 hours

After 5 failed attempts, FormLeap stops retrying and marks the webhook as failed.

Testing Webhooks

Option 1: Use a Service

Test with webhook.site or requestbin.com:

  1. Visit https://webhook.site
  2. Copy your unique URL
  3. Add it as a webhook in FormLeap
  4. Submit a test form
  5. View the request payload

Option 2: Local Development

Use ngrok to expose your local server:

# Start your local server on port 3000
npm start

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook
https://abc123.ngrok.io/webhooks/formleap

Webhook Logs

View webhook delivery logs:

  1. Open Form Settings → Integrations → Webhooks
  2. Click View Logs next to your webhook
  3. See recent deliveries with:
    • Timestamp
    • Status code
    • Response time
    • Retry attempts

Embedding Forms

Add FormLeap forms directly to your website.

Embedding Methods

1. Direct Link:

  • Simplest option
  • Redirects user to FormLeap-hosted form
  • Best for: Quick setup

2. Iframe Embed:

  • Embeds form inside your page
  • Stays on your domain
  • Best for: Seamless integration

3. Script Embed (Coming Soon):

  • JavaScript-based embedding
  • Responsive and customizable
  • Best for: Advanced customization

Direct Link

Share the form URL directly:

<a href="https://formleap.app/f/your-form-id">Fill out our form</a>

Users click the link and are taken to the FormLeap-hosted form.

Iframe Embed

Embed the form within your page:

<iframe
  src="https://formleap.app/f/your-form-id"
  width="100%"
  height="800"
  frameborder="0"
  style="border: none; border-radius: 8px;">
</iframe>

Customization:

<iframe
  src="https://formleap.app/f/your-form-id?embed=true"
  width="100%"
  height="800"
  frameborder="0"
  style="border: none;">
</iframe>

The embed=true parameter:

  • Removes FormLeap branding (Pro+ plans)
  • Adjusts styling for embedding
  • Enables auto-resize messages

Getting the Embed Code

  1. Open your form in the builder
  2. Click Share button
  3. Click Embed tab
  4. Copy the embed code
  5. Paste into your website HTML

Responsive Embedding

Make the iframe responsive with CSS:

<style>
  .formleap-embed {
    position: relative;
    padding-bottom: 100%; /* Adjust based on form height */
    height: 0;
    overflow: hidden;
  }

  .formleap-embed iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
</style>

<div class="formleap-embed">
  <iframe src="https://formleap.app/f/your-form-id"></iframe>
</div>

Auto-Resize (Coming Soon)

The script embed will automatically resize based on form height, eliminating scrollbars.

Reference Fields

Pass contextual data to forms via URL parameters.

What are Reference Fields?

Reference fields let you embed information in the form URL that gets stored with each submission.

Use Cases:

  • Track which blog post a comment came from
  • Identify which product a question is about
  • Record the marketing source
  • Link submissions to user accounts
  • Track campaign IDs

Setting Up Reference Fields

  1. Open Form Settings → Submissions
  2. Scroll to Reference Fields
  3. Add field names (one per line): 
    article_id
source
campaign
user_id
  4. Click Save

Only configured fields are captured. Others are ignored for security.

Using Reference Fields

Add parameters to your form URL:

https://formleap.app/f/your-form-id?article_id=123&source=blog

When someone submits the form, the submission includes:

{
  "reference_data": {
    "article_id": "123",
    "source": "blog"
  }
}

Viewing Reference Data

Reference data appears in:

  • Submission details - Under "Reference Data" section
  • CSV exports - Columns prefixed with ref:
  • Webhook payloads - submission.reference_data object
  • API responses - reference_data field

CSV Example:

Submitted At,ref:article_id,ref:source,Name,Email
2025-01-20,123,blog,John Doe,john@example.com

Dynamic URLs

Generate dynamic URLs programmatically:

const formId = 'your-form-id';
const articleId = '123';
const source = 'blog';

const url = `https://formleap.app/f/${formId}?article_id=${articleId}&source=${source}`;

// Use in a link
document.querySelector('a').href = url;

PHP:

$form_id = 'your-form-id';
$article_id = '123';
$source = 'blog';

$url = "https://formleap.app/f/{$form_id}?article_id={$article_id}&source={$source}";

echo "<a href='{$url}'>Contact Us</a>";

Best Practices

  1. Keep names short - Use article_id not blog_article_identifier
  2. Use underscores - Not hyphens or spaces
  3. Be consistent - Use the same naming across forms
  4. Don't include sensitive data - URLs are visible to users
  5. URL encode values - Escape special characters

API Access

Available on: Pro, Business, and Enterprise plans

Programmatically access forms and submissions via REST API.

API Overview

The FormLeap API allows you to:

  • Create, read, update, and delete forms
  • Retrieve submissions
  • Search submissions
  • Export data

Base URL:

https://formleap.app/api/v1

Authentication

Authenticate with API keys:

curl https://formleap.app/api/v1/forms \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting an API Key:

  1. Go to Account Settings → API
  2. Click Create API Key
  3. Enter a name (e.g., "Production Server")
  4. Copy the key (shown only once)
  5. Store securely

Quick Example

List all your forms:

curl https://formleap.app/api/v1/forms \
  -H "Authorization: Bearer YOUR_API_KEY"

Get submissions for a form:

curl https://formleap.app/api/v1/forms/FORM_ID/submissions \
  -H "Authorization: Bearer YOUR_API_KEY"

Documentation

For complete API documentation, see:

API Reference →

The API reference includes:

  • All endpoints
  • Request/response examples
  • Error codes
  • Rate limits
  • Full cURL and JavaScript examples

AI Integration (MCP)

Available on: Business and Enterprise plans

Create forms from PDFs or natural language using the Model Context Protocol (MCP).

What is MCP?

MCP (Model Context Protocol) allows AI assistants like Claude to interact with FormLeap:

  • Upload a PDF form → Generate a live digital form
  • Describe your form → AI creates it for you
  • Natural language form editing
  • Bulk form operations

Setting Up MCP

For Claude Desktop:

See the full MCP Integration Guide → for setup instructions.

Quick Start:

  1. Install the FormLeap MCP server
  2. Configure authentication
  3. Use Claude to create forms

Example Prompt:

Create a job application form with fields for name, email,
resume upload, cover letter, years of experience, and
preferred start date.

Claude will generate a complete form with proper field types and validation.

MCP Documentation

For complete MCP setup and usage, see:

MCP Integration Guide →

Best Practices

Webhooks

  1. Verify signatures - Always validate webhook authenticity
  2. Respond quickly - Return 200 OK within 10 seconds
  3. Process async - Queue long-running tasks
  4. Handle retries - Make endpoints idempotent
  5. Log failures - Monitor webhook delivery logs

Embedding

  1. Use HTTPS - Always embed over secure connections
  2. Set appropriate height - Avoid excessive scrolling
  3. Test on mobile - Ensure responsive design
  4. Match your brand - Use theming to maintain consistency
  5. Monitor performance - Check form load times

Reference Fields

  1. Whitelist fields - Only configure fields you need
  2. Validate server-side - Don't trust URL parameters for security
  3. Document your fields - Keep a list of what each means
  4. URL encode properly - Escape special characters
  5. Don't expose secrets - Never pass sensitive data in URLs

API Usage

  1. Rate limit awareness - Respect rate limits
  2. Cache when possible - Reduce unnecessary requests
  3. Handle errors gracefully - Implement retry logic
  4. Secure API keys - Never commit keys to version control
  5. Use environment variables - Store keys securely

What's Next?

Need help? Contact support@formleap.app

Previous
Teams & Collaboration