> ## Documentation Index
> Fetch the complete documentation index at: https://help.topformbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Integration Guide

> Send form submissions to any external URL in real-time using webhooks. Perfect for custom integrations and automation.

## What are Webhooks?

Webhooks send HTTP POST requests to your specified URL when someone submits your form.

**Use Cases:**

* Custom CRM integration
* Trigger automation workflows
* Update external databases
* Send data to your own server
* Real-time data sync
* Trigger third-party services
* Custom notification systems

## How Webhooks Work

1. **User submits form** → TopFormBuilder captures submission
2. **Webhook triggers** → Sends POST request to your URL
3. **Your server receives** → Processes submission data
4. **Response returned** → Success or failure status

**Real-time:** Webhooks fire immediately after form submission (within seconds)

## Setting Up Webhooks

### Step 1: Prepare Your Endpoint

Before adding webhook in TopFormBuilder, prepare your receiving endpoint:

**Requirements:**

* Public HTTPS URL (SSL required)
* Accepts POST requests
* Returns HTTP 200 status on success
* Responds within 30 seconds (timeout)

**Example URL:**

```
https://yourdomain.com/api/webhooks/topformbuilder
```

### Step 2: Add Webhook Integration

1. Open your form in Form Builder
2. Go to **Settings** tab
3. Click **Integrations** section
4. Click **"Add Integration"**
5. Select **"Webhook"**

### Step 3: Configure Webhook

**Webhook URL** (required)

* Enter your endpoint URL
* Must start with `https://`
* Example: `https://api.yoursite.com/webhooks/forms`

**Custom Headers** (optional)

* Add authentication headers
* Example: `Authorization: Bearer YOUR_TOKEN`
* Format: `Header-Name: Value` (one per line)

**Secret Key** (recommended)

* Shared secret for verification
* Used to sign requests
* Verify webhook authenticity
* Generate secure random string

**Retry Failed Requests**

* ☑ Auto-retry on failure (recommended)
* Retries up to 3 times
* Exponential backoff (1s, 5s, 15s delays)

**Timeout**

* Default: 30 seconds
* Maximum wait for response
* Fails if no response within timeout

### Step 4: Test Webhook

1. Click **"Test Webhook"** button
2. Sample data sent to your URL
3. Check your server receives data
4. Verify response status 200
5. Review payload format

**If test fails:**

* Check URL is correct and accessible
* Verify server accepts POST requests
* Check firewall/security settings
* Review server logs for errors

### Step 5: Save & Activate

1. Click **"Save Integration"**
2. Toggle **"Active"** to ON
3. Webhook is now live!

## Webhook Payload

### Request Format

**Method:** POST **Content-Type:** application/json **Body:** JSON object with submission data

### Payload Structure

```json theme={null}
{
  "event": "form.submission.created",
  "form_id": 123,
  "form_name": "Customer Feedback Survey",
  "form_slug": "customer-feedback",
  "submission_id": 456,
  "submitted_at": "2024-03-15T10:30:00Z",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "device_type": "desktop",
  "time_taken": 125,
  "answers": [
    {
      "block_id": 1,
      "question": "What's your name?",
      "answer": "John Doe",
      "type": "short_text"
    },
    {
      "block_id": 2,
      "question": "Email address?",
      "answer": "john@example.com",
      "type": "email"
    },
    {
      "block_id": 3,
      "question": "How would you rate us?",
      "answer": 5,
      "type": "rating"
    }
  ],
  "metadata": {
    "location": {
      "country": "US",
      "city": "New York"
    },
    "referrer": "https://google.com",
    "utm_source": "email",
    "utm_campaign": "spring2024"
  }
}
```

### Headers Sent

**Standard Headers:**

```
POST /webhook HTTP/1.1
Host: yourdomain.com
Content-Type: application/json
Content-Length: 1234
User-Agent: TopFormBuilder-Webhook/1.0
X-TFB-Event: form.submission.created
X-TFB-Signature: sha256=abc123...
X-TFB-Delivery: uuid-goes-here
```

**Custom Headers:** Any headers you configured are included

## Verifying Webhooks

### Signature Verification (Recommended)

Verify webhook authenticity using HMAC signature:

**Signature Header:** `X-TFB-Signature` **Format:** `sha256=<signature>`

**Verification Steps:**

1. Extract signature from header
2. Compute HMAC of request body using your secret key
3. Compare signatures
4. Accept request if signatures match

**Example (Node.js):**

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhook(request, secret) {
  const signature = request.headers['x-tfb-signature'];
  const body = JSON.stringify(request.body);

  const expectedSignature = 'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(body)
      .digest('hex');

  return signature === expectedSignature;
}
```

**Example (PHP):**

```php theme={null}
function verifyWebhook($request, $secret) {
    $signature = $request->header('X-TFB-Signature');
    $body = $request->getContent();

    $expectedSignature = 'sha256=' .
        hash_hmac('sha256', $body, $secret);

    return hash_equals($signature, $expectedSignature);
}
```

**Example (Python):**

```python theme={null}
import hmac
import hashlib

def verify_webhook(request, secret):
    signature = request.headers.get('X-TFB-Signature')
    body = request.get_data()

    expected_signature = 'sha256=' + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)
```

## Handling Webhooks

### Responding to Webhooks

**Success Response:**

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Webhook received"
}
```

**Failure Response:**

```http theme={null}
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "success": false,
  "error": "Database connection failed"
}
```

**Best Practices:**

* Return 200 status immediately
* Process webhook asynchronously (queue/background job)
* Don't make webhook wait for long operations
* Log webhook data for debugging

### Processing Submissions

**Example Processing Flow:**

1. **Receive webhook** → Validate signature
2. **Parse JSON** → Extract submission data
3. **Queue job** → Add to background queue
4. **Return 200** → Acknowledge receipt quickly
5. **Process async** → Handle data in background

### Retry Logic

**Automatic Retries:**

* Retry 1: After 1 second
* Retry 2: After 5 seconds
* Retry 3: After 15 seconds
* Max retries: 3 attempts

**Retries Triggered When:**

* HTTP status code ≠ 200
* Connection timeout (30s)
* Connection refused
* SSL errors

**Retries Not Triggered When:**

* 200 status returned (even if response body has errors)
* 400-499 client errors (invalid request)

**Disable Retries:**

* Uncheck "Retry Failed Requests" in settings
* Webhook only fires once

## Webhook Events

### Available Events

**form.submission.created** (default)

* New form submission received
* Most common event
* Includes all submission data

**form.submission.updated** (coming soon)

* Submission edited/updated
* Includes updated data

**form.submission.deleted** (coming soon)

* Submission deleted
* Includes submission ID only

## Monitoring Webhooks

### Webhook Logs

View webhook delivery history:

1. Go to **Form → Integrations**
2. Click **"View Logs"** on webhook integration
3. See all webhook deliveries

**Log Information:**

* Delivery ID
* Timestamp
* Status (success/failure)
* HTTP status code
* Response body
* Response time
* Retry attempts

**Filtering Logs:**

* Last 24 hours
* Last 7 days
* Last 30 days
* All time

### Retry Failed Webhooks

Manually retry failed deliveries:

1. Go to webhook logs
2. Find failed delivery
3. Click **"Retry"** button
4. Webhook resent immediately
5. Check new delivery status

## Common Integrations

### Zapier Alternative

Use webhooks to connect with thousands of apps:

1. Create Zapier Zap with "Webhooks by Zapier" trigger
2. Copy webhook URL from Zapier
3. Paste into TopFormBuilder webhook integration
4. Connect to any Zapier-supported app

### Make (Integromat) Alternative

Similar to Zapier:

1. Create Make scenario with "Webhooks" module
2. Copy webhook URL
3. Add to TopFormBuilder
4. Build automation workflow

### Custom CRM

Send leads directly to your CRM:

```javascript theme={null}
// Example: Your server receives webhook
app.post('/webhooks/topformbuilder', (req, res) => {
  const submission = req.body;

  // Add lead to CRM
  await crm.leads.create({
    name: submission.answers.find(a => a.type === 'short_text').answer,
    email: submission.answers.find(a => a.type === 'email').answer,
    source: 'TopFormBuilder',
    form_name: submission.form_name
  });

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

### Database Integration

Store submissions in your database:

```python theme={null}
# Example: Flask app receives webhook
@app.route('/webhooks/forms', methods=['POST'])
def handle_webhook():
    data = request.json

    # Insert into database
    db.submissions.insert({
        'form_id': data['form_id'],
        'submission_id': data['submission_id'],
        'answers': data['answers'],
        'submitted_at': data['submitted_at']
    })

    return {'success': True}, 200
```

## Security Best Practices

**Do:**

* Use HTTPS only (never HTTP)
* Verify webhook signatures
* Whitelist TopFormBuilder IPs (optional)
* Rate limit webhook endpoint
* Log all webhook deliveries
* Use secrets for authentication

**Don't:**

* Expose webhook URL publicly
* Skip signature verification
* Process webhooks synchronously (timeout risk)
* Return sensitive data in response
* Trust webhook data without validation

## Troubleshooting

### "Webhook delivery failed"

**Problem:** Webhook not reaching your server

**Solutions:**

* Verify URL is correct and accessible
* Check server is running
* Ensure HTTPS (not HTTP)
* Check firewall allows incoming requests
* Review server logs for errors
* Test with curl/Postman

### "Timeout error"

**Problem:** Server not responding within 30 seconds

**Solutions:**

* Return 200 immediately
* Process webhook asynchronously
* Optimize server performance
* Increase server resources

### "SSL certificate error"

**Problem:** Invalid SSL certificate

**Solutions:**

* Ensure valid SSL certificate installed
* Check certificate not expired
* Verify domain matches certificate
* Use trusted CA (not self-signed)

### "Signature verification failed"

**Problem:** Signature doesn't match

**Solutions:**

* Check secret key is correct
* Verify using raw request body (not parsed JSON)
* Check HMAC algorithm (SHA256)
* Ensure UTF-8 encoding

***

[**Need help? Contact contact@topformbuilder.com**](mailto:contact@topformbuilder.com)