Key Takeaways

Webhooks enable real-time form submission notifications to any HTTP endpoint
JSON payloads provide structured data for easy parsing and processing
Webhook signature verification ensures secure, authenticated data transfer
Error handling and retry logic create robust integration architectures

Modern applications require seamless data flow between forms and backend systems. Webhooks provide the foundation for real-time integrations, enabling you to receive form submissions instantly and process them however your application needs.

Understanding Webhook Architecture

Webhooks follow an event-driven pattern: when a form is submitted, Pixelform sends a POST request to your specified endpoint with the submission data.

Webhook Flow:

User submits form
    ↓
Pixelform processes submission
    ↓
POST request sent to your webhook URL
    ↓
Your server receives and processes data
    ↓
Response confirms receipt

This architecture provides several advantages:

Real-time delivery — No polling required
Server-to-server — Secure data transfer
Flexible processing — Handle data however you need
Integration ready — Connect to any system that accepts HTTP requests

Webhook Payload Structure

When a form is submitted, your endpoint receives a JSON payload containing all submission data:

{
  "event": "submission.created",
  "timestamp": "2025-01-07T10:30:00Z",
  "form_id": "form_abc123",
  "form_name": "Contact Form",
  "submission_id": "sub_xyz789",
  "data": {
    "name": "John Smith",
    "email": "john@company.com",
    "company": "Acme Inc",
    "message": "I have a question about pricing"
  },
  "metadata": {
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0...",
    "referrer": "https://example.com/contact",
    "submitted_at": "2025-01-07T10:30:00Z"
  }
}

Field Mapping

Each form field is included in the data object:

Form Field Type	JSON Value Type
Text input	String
Email	String
Number	Number
Date picker	ISO 8601 string
Dropdown	Selected option value
Checkbox group	Array of selected values
File upload	Object with URL and metadata

Setting Up Your Webhook

Step 1: Create Your Endpoint

Your webhook endpoint must:

Accept POST requests
Parse JSON request body
Return 200 status for successful processing
Handle errors gracefully

Example: Express.js Webhook Handler

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/form-submission', async (req, res) => {
  try {
    const { event, form_id, submission_id, data } = req.body;

    console.log(`New submission ${submission_id} from form ${form_id}`);

    // Process the submission
    await processSubmission(data);

    // Respond with success
    res.status(200).json({ received: true });

  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

async function processSubmission(data) {
  // Save to database
  await db.submissions.create({ data });

  // Send to CRM
  await crm.createLead({
    email: data.email,
    name: data.name,
    source: 'Website Form'
  });

  // Notify team
  await slack.sendMessage('#leads', `New lead: ${data.name}`);
}

app.listen(3000);

Step 2: Configure in Pixelform

Go to your form settings
Navigate to Integrations > Webhooks
Click “Add Webhook”
Enter your endpoint URL
Select events to trigger (e.g., submission.created)
Save and test

Step 3: Test Your Integration

Use Pixelform’s test submission feature to verify your webhook:

Click “Send Test” in webhook settings
Check your server logs for the request
Verify data processing works correctly
Confirm 200 response is returned

Webhook Security

Signature Verification

Verify that webhook requests actually came from Pixelform using HMAC signature verification:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/form-submission', (req, res) => {
  const signature = req.headers['x-pixelform-signature'];
  const webhookSecret = process.env.WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, webhookSecret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process verified webhook...
});

Security Best Practices

Use HTTPS — Never accept webhooks over plain HTTP
Verify signatures — Confirm requests are from Pixelform
Validate payload — Check expected fields exist
Rate limit — Protect against flood attacks
Timeout handling — Set reasonable processing timeouts

Error Handling and Retries

Implementing Retry Logic

If your endpoint returns an error, implement retry logic:

async function processWithRetry(data, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      await processSubmission(data);
      return; // Success
    } catch (error) {
      if (attempt === maxRetries - 1) {
        // Final attempt failed
        await logFailure(data, error);
        throw error;
      }
      // Wait before retry (exponential backoff)
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Response Status Codes

Status Code	Meaning	Pixelform Action
200-299	Success	Mark as delivered
400-499	Client error	Log error, no retry
500-599	Server error	Retry with backoff
Timeout	No response	Retry with backoff

Common Integration Patterns

CRM Integration

async function processSubmission(data) {
  const crmContact = {
    email: data.email,
    firstName: data.first_name,
    lastName: data.last_name,
    company: data.company,
    source: 'Website Form',
    leadScore: calculateLeadScore(data)
  };

  // Check if contact exists
  const existing = await crm.findByEmail(data.email);

  if (existing) {
    await crm.updateContact(existing.id, crmContact);
  } else {
    await crm.createContact(crmContact);
  }
}

Slack Notification

async function notifySlack(data) {
  const message = {
    channel: '#new-leads',
    blocks: [
      {
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: `*New form submission*\n${data.name} (${data.email})`
        }
      },
      {
        type: 'section',
        fields: [
          { type: 'mrkdwn', text: `*Company:*\n${data.company}` },
          { type: 'mrkdwn', text: `*Message:*\n${data.message}` }
        ]
      }
    ]
  };

  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(message)
  });
}

Database Storage

// Using Prisma ORM
async function saveSubmission(formId, submissionId, data, metadata) {
  await prisma.submission.create({
    data: {
      id: submissionId,
      formId: formId,
      data: data,
      ipAddress: metadata.ip_address,
      userAgent: metadata.user_agent,
      submittedAt: new Date(metadata.submitted_at)
    }
  });
}

Email Forwarding

async function forwardToEmail(data, recipients) {
  const emailContent = Object.entries(data)
    .map(([key, value]) => `${key}: ${value}`)
    .join('\n');

  await sendEmail({
    to: recipients,
    subject: `New Form Submission: ${data.name}`,
    text: emailContent
  });
}

Serverless Webhook Handlers

Deploy webhook handlers without managing servers:

AWS Lambda

// handler.js
exports.handler = async (event) => {
  const body = JSON.parse(event.body);

  await processSubmission(body.data);

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true })
  };
};

Vercel Serverless Functions

// api/webhook.js
export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { data } = req.body;
  await processSubmission(data);

  res.status(200).json({ received: true });
}

Cloudflare Workers

export default {
  async fetch(request) {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 });
    }

    const body = await request.json();
    await processSubmission(body.data);

    return new Response(JSON.stringify({ received: true }), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

Testing and Debugging

Local Development

Use ngrok or similar tools to expose your local server:

# Start your local server
npm start

# In another terminal, create a tunnel
ngrok http 3000

Use the ngrok URL as your webhook endpoint for testing.

Logging Best Practices

app.post('/webhooks/form-submission', async (req, res) => {
  const startTime = Date.now();
  const { submission_id, form_id } = req.body;

  console.log({
    event: 'webhook_received',
    submission_id,
    form_id,
    timestamp: new Date().toISOString()
  });

  try {
    await processSubmission(req.body.data);

    console.log({
      event: 'webhook_processed',
      submission_id,
      duration_ms: Date.now() - startTime
    });

    res.status(200).json({ received: true });

  } catch (error) {
    console.error({
      event: 'webhook_error',
      submission_id,
      error: error.message,
      stack: error.stack
    });

    res.status(500).json({ error: 'Processing failed' });
  }
});

FAQ

How quickly are webhooks delivered after form submission?

Webhooks are sent immediately after form submission is processed, typically within 1-2 seconds. Network latency and your server’s response time may add slight delays. For time-critical applications, ensure your endpoint responds quickly and processes heavy operations asynchronously.

What happens if my webhook endpoint is down?

If your endpoint returns an error or times out, the webhook delivery will be retried with exponential backoff. Most webhook systems retry 3-5 times over several hours. Implement proper error logging to catch issues, and consider a queue-based architecture for critical data processing.

Can I receive webhooks for multiple forms to the same endpoint?

Yes, each webhook payload includes form_id and form_name fields, allowing you to route different forms to different processing logic within the same endpoint. Use conditional logic based on form_id to handle each form type appropriately.

How do I ensure webhook security?

Always use HTTPS endpoints and implement signature verification. Each webhook includes a cryptographic signature in the headers that you can verify using your webhook secret. This confirms the request genuinely came from Pixelform and wasn’t tampered with in transit.

What’s the webhook request timeout?

Webhook requests typically timeout after 30 seconds. If your processing takes longer, return a 200 response immediately and process the data asynchronously using a job queue like Bull, RabbitMQ, or AWS SQS.

Start Building with Webhooks

Pixelform provides powerful webhook integrations for real-time form data processing. Send submissions to any system, build custom workflows, and integrate with your existing infrastructure.

Get started with webhook integrations — webhooks included on all plans.

Form Webhook Integration Guide for Developers