Setting up webhooks in embed forms

Learn how to configure webhooks to receive real-time notifications when someone submits your embed form.

What Are Webhooks?

Webhooks allow you to receive real-time notifications when someone submits your embed form. This enables you to:

Send automated emails to new leads
Add leads to your CRM system
Trigger other automated workflows
Sync data with external systems
Integrate with marketing automation tools

Setting Up a Webhook

Step 1: Edit Your Form
Open the form builder for the form you want to configure.

Step 2: Go to Webhooks Tab
In the form builder, navigate to the “Webhooks” section.

Step 3: Enter Webhook URL
Enter the URL where you want to receive webhook notifications (e.g., https://yourdomain.com/webhook).

Step 4: Save Form
Click “Save Form” to activate the webhook.

Webhook Payload

When a form is submitted, your webhook endpoint will receive a POST request with this JSON payload:

{
  "event": "form_submission",
  "form_id": "123",
  "submission_id": "abc-123-def",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "full_name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "birth_date": "1990-01-15",
    "birth_time": "14:30:00",
    "birth_location": "New York, NY, USA",
    "timezone": "America/New_York"
  },
  "chart_id": "chart-123",
  "chart_data": {
    "Properties": {
      "Type": { "Option": "Generator" },
      "Profile": { "Option": "1/3" },
      "Strategy": { "Option": "To Respond" },
      "InnerAuthority": { "Option": "Sacral" }
    },
    "Design": { /* planetary positions */ },
    "Personality": { /* planetary positions */ }
  },
  "source_url": "https://yourwebsite.com/page",
  "referrer_url": "https://google.com",
  "show_chart_on_success": true,
  "collect_leads": true
}

Webhook Requirements

Your webhook endpoint must:

Accept POST requests
Accept JSON content type
Return a 2xx status code (200, 201, 202) for successful processing
Respond within 30 seconds (webhook calls timeout after 30s)

Testing Webhooks

Step 1: Set Up Test Endpoint
Use a service like webhook.site to get a temporary test URL.

Step 2: Enter Test URL
Enter the test URL in your form’s webhook settings and save.

Step 3: Submit Test Form
Submit a test form using your embed form.

Step 4: Verify Payload
Check your webhook endpoint to verify the payload was received correctly.

Webhook Security

For production use, consider:

Use HTTPS: Always use HTTPS for your webhook URL
Validate Payload: Verify the webhook payload structure matches expected format
Rate Limiting: Implement rate limiting on your webhook endpoint
Error Handling: Handle errors gracefully and log failed webhook calls

Note: Webhook calls are “fire and forget” – they don’t block form submission. If your webhook fails, the form submission will still succeed and the lead will still be captured in your CRM.

Common Use Cases

Email Notifications

Send an email notification when a new lead is captured:

// Example webhook handler (Node.js)
app.post('/webhook', async (req, res) => {
  const { data, email } = req.body;
  
  // Send email notification
  await sendEmail({
    to: 'you@example.com',
    subject: 'New Lead: ' + data.full_name,
    body: `New lead captured: ${data.full_name} (${email})`
  });
  
  res.status(200).json({ success: true });
});

CRM Integration

Add leads to your CRM system:

// Example webhook handler
app.post('/webhook', async (req, res) => {
  const { data, chart_data } = req.body;
  
  // Add to CRM
  await crm.createContact({
    name: data.full_name,
    email: data.email,
    phone: data.phone,
    customFields: {
      human_design_type: chart_data.Properties.Type.Option,
      human_design_profile: chart_data.Properties.Profile.Option
    }
  });
  
  res.status(200).json({ success: true });
});

Troubleshooting

Webhook Not Receiving Notifications

Verify the webhook URL is correct and accessible
Check that your endpoint accepts POST requests
Test the endpoint with a tool like Postman
Check Supabase Edge Function logs for webhook errors
Ensure your endpoint responds within 30 seconds

Webhook Returns Errors

Check that your endpoint returns a 2xx status code
Verify JSON parsing is working correctly
Check server logs for detailed error messages
Ensure your endpoint can handle the payload size

Important: Webhook responses are logged in Supabase Edge Function logs. Check the submit-embed-form function logs to see webhook call status and responses.