Skip to main content
Arcanflows

Webhook Integration

Send form submissions to external endpoints for custom processing and third-party integrations.

Overview

Webhooks allow you to send form submission data to external URLs in real-time. Use webhooks to integrate with third-party services, custom APIs, or any HTTP endpoint.

Basic Configuration

Simple Webhook

json
{
  "webhooks": [
    {
      "url": "https://your-api.com/webhook/form-submission",
      "enabled": true
    }
  ]
}

With Authentication

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/submissions",
      "enabled": true,
      "auth": {
        "type": "bearer",
        "token": "your_api_token"
      }
    }
  ]
}

Multiple Webhooks

json
{
  "webhooks": [
    {
      "name": "CRM Integration",
      "url": "https://crm.example.com/api/leads",
      "enabled": true
    },
    {
      "name": "Email Service",
      "url": "https://email.example.com/api/contacts",
      "enabled": true
    },
    {
      "name": "Analytics",
      "url": "https://analytics.example.com/events",
      "enabled": true
    }
  ]
}

Request Configuration

HTTP Method

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/submissions",
      "method": "POST"
    }
  ]
}

Supported methods:

  • POST (default)
  • PUT
  • PATCH

Custom Headers

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "headers": {
        "Content-Type": "application/json",
        "X-API-Version": "2024-01",
        "X-Source": "arcanflows-form",
        "X-Form-ID": "{{_formId}}"
      }
    }
  ]
}

Content Types

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "contentType": "application/json"
    }
  ]
}

Supported types:

  • application/json (default)
  • application/x-www-form-urlencoded
  • multipart/form-data

Authentication

API Key

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "auth": {
        "type": "api_key",
        "header": "X-API-Key",
        "value": "your_api_key_here"
      }
    }
  ]
}

Bearer Token

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "auth": {
        "type": "bearer",
        "token": "your_bearer_token"
      }
    }
  ]
}

Basic Auth

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "auth": {
        "type": "basic",
        "username": "your_username",
        "password": "your_password"
      }
    }
  ]
}

OAuth 2.0

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "auth": {
        "type": "oauth2",
        "tokenUrl": "https://auth.example.com/oauth/token",
        "clientId": "your_client_id",
        "clientSecret": "your_client_secret",
        "scope": "webhooks:write"
      }
    }
  ]
}

Signature Verification

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "signature": {
        "enabled": true,
        "secret": "your_webhook_secret",
        "algorithm": "sha256",
        "header": "X-Signature"
      }
    }
  ]
}

Payload Configuration

Default Payload

All form fields sent with metadata:

json
{
  "event": "form.submitted",
  "formId": "form_abc123",
  "submissionId": "sub_xyz789",
  "submittedAt": "2025-01-15T10:30:00Z",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "message": "Hello world"
  },
  "metadata": {
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "referrer": "https://google.com",
    "pageUrl": "https://yoursite.com/contact"
  }
}

Custom Payload

json
{
  "webhooks": [
    {
      "url": "https://crm.example.com/api/leads",
      "payload": {
        "lead": {
          "name": "{{firstName}} {{lastName}}",
          "email": "{{email}}",
          "phone": "{{phone}}",
          "source": "Website Contact Form"
        },
        "metadata": {
          "form": "{{_formId}}",
          "timestamp": "{{_submittedAt}}"
        }
      }
    }
  ]
}

Field Mapping

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/contacts",
      "payload": {
        "properties": {
          "firstname": "{{firstName}}",
          "lastname": "{{lastName}}",
          "email": "{{email}}",
          "company": "{{company}}",
          "jobtitle": "{{jobTitle}}"
        }
      }
    }
  ]
}

Transform Data

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "transforms": {
        "email": "lowercase({{email}})",
        "name": "uppercase({{firstName}})",
        "tags": "split({{interests}}, ',')",
        "score": "parseInt({{rating}})"
      }
    }
  ]
}

Include/Exclude Fields

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "fields": {
        "include": ["firstName", "lastName", "email"],
        "exclude": ["password", "creditCard"]
      }
    }
  ]
}

Conditional Webhooks

Based on Field Values

json
{
  "webhooks": [
    {
      "name": "Sales CRM",
      "url": "https://sales.crm.com/leads",
      "condition": {
        "field": "inquiryType",
        "operator": "equals",
        "value": "sales"
      }
    },
    {
      "name": "Support System",
      "url": "https://support.example.com/tickets",
      "condition": {
        "field": "inquiryType",
        "operator": "equals",
        "value": "support"
      }
    }
  ]
}

Complex Conditions

json
{
  "webhooks": [
    {
      "name": "Enterprise Leads",
      "url": "https://enterprise.crm.com/leads",
      "condition": {
        "logic": "and",
        "rules": [
          { "field": "companySize", "operator": "greaterThan", "value": 500 },
          { "field": "budget", "operator": "greaterThan", "value": 50000 }
        ]
      }
    }
  ]
}

Expression-Based

json
{
  "webhooks": [
    {
      "name": "High Priority",
      "url": "https://alerts.example.com/urgent",
      "conditionExpression": "{{priority}} === 'urgent' || {{revenue}} > 100000"
    }
  ]
}

Error Handling

Retry Configuration

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "retry": {
        "enabled": true,
        "maxAttempts": 3,
        "backoffMs": [1000, 5000, 15000]
      }
    }
  ]
}

Timeout Settings

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "timeout": 10000,
      "retry": {
        "enabled": true,
        "retryOn": [408, 429, 500, 502, 503, 504]
      }
    }
  ]
}

Failure Actions

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "onFailure": {
        "action": "queue",
        "notify": {
          "email": "[email protected]",
          "slack": "#webhook-failures"
        },
        "fallback": {
          "url": "https://backup-api.example.com/webhook"
        }
      }
    }
  ]
}

Dead Letter Queue

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "deadLetterQueue": {
        "enabled": true,
        "retentionDays": 30,
        "alertThreshold": 10
      }
    }
  ]
}

Common Integrations

Slack

json
{
  "webhooks": [
    {
      "name": "Slack Notification",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "payload": {
        "text": "New form submission from {{firstName}} {{lastName}}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*New Contact Form Submission*\n\n*Name:* {{firstName}} {{lastName}}\n*Email:* {{email}}\n*Message:* {{message}}"
            }
          }
        ]
      }
    }
  ]
}

Zapier

json
{
  "webhooks": [
    {
      "name": "Zapier Trigger",
      "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
      "payload": {
        "name": "{{firstName}} {{lastName}}",
        "email": "{{email}}",
        "phone": "{{phone}}",
        "company": "{{company}}",
        "source": "website_form"
      }
    }
  ]
}

HubSpot

json
{
  "webhooks": [
    {
      "name": "HubSpot Contact",
      "url": "https://api.hubapi.com/contacts/v1/contact",
      "method": "POST",
      "auth": {
        "type": "bearer",
        "token": "{{HUBSPOT_API_KEY}}"
      },
      "payload": {
        "properties": [
          { "property": "firstname", "value": "{{firstName}}" },
          { "property": "lastname", "value": "{{lastName}}" },
          { "property": "email", "value": "{{email}}" },
          { "property": "company", "value": "{{company}}" }
        ]
      }
    }
  ]
}

Salesforce

json
{
  "webhooks": [
    {
      "name": "Salesforce Lead",
      "url": "https://your-instance.salesforce.com/services/data/v57.0/sobjects/Lead",
      "method": "POST",
      "auth": {
        "type": "oauth2",
        "tokenUrl": "https://login.salesforce.com/services/oauth2/token",
        "clientId": "{{SF_CLIENT_ID}}",
        "clientSecret": "{{SF_CLIENT_SECRET}}"
      },
      "payload": {
        "FirstName": "{{firstName}}",
        "LastName": "{{lastName}}",
        "Email": "{{email}}",
        "Company": "{{company}}",
        "LeadSource": "Web Form"
      }
    }
  ]
}

Mailchimp

json
{
  "webhooks": [
    {
      "name": "Mailchimp Subscribe",
      "url": "https://us1.api.mailchimp.com/3.0/lists/list_id/members",
      "method": "POST",
      "auth": {
        "type": "basic",
        "username": "anystring",
        "password": "{{MAILCHIMP_API_KEY}}"
      },
      "payload": {
        "email_address": "{{email}}",
        "status": "subscribed",
        "merge_fields": {
          "FNAME": "{{firstName}}",
          "LNAME": "{{lastName}}"
        }
      }
    }
  ]
}

Google Sheets

json
{
  "webhooks": [
    {
      "name": "Google Sheets",
      "url": "https://script.google.com/macros/s/your_script_id/exec",
      "method": "POST",
      "payload": {
        "sheetName": "Form Submissions",
        "data": {
          "timestamp": "{{_submittedAt}}",
          "name": "{{firstName}} {{lastName}}",
          "email": "{{email}}",
          "phone": "{{phone}}",
          "message": "{{message}}"
        }
      }
    }
  ]
}

Testing

Test Mode

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "testMode": {
        "enabled": true,
        "logPayload": true,
        "mockResponse": {
          "status": 200,
          "body": { "success": true }
        }
      }
    }
  ]
}

Webhook Inspector

json
{
  "webhooks": [
    {
      "url": "https://webhook.site/unique-id",
      "name": "Debug Webhook"
    }
  ]
}

Monitoring

Logging

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "logging": {
        "enabled": true,
        "level": "detailed",
        "includePayload": true,
        "includeResponse": true
      }
    }
  ]
}

Metrics

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "metrics": {
        "enabled": true,
        "trackLatency": true,
        "trackSuccessRate": true
      }
    }
  ]
}

Alerts

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "alerts": {
        "onConsecutiveFailures": 3,
        "onLatencyMs": 5000,
        "notify": ["[email protected]"]
      }
    }
  ]
}

Security

IP Whitelist

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "security": {
        "validateSSL": true,
        "allowedIPs": ["203.0.113.0/24"]
      }
    }
  ]
}

Sensitive Data

json
{
  "webhooks": [
    {
      "url": "https://api.example.com/webhook",
      "security": {
        "excludeFields": ["password", "ssn", "creditCard"],
        "maskFields": ["email", "phone"],
        "encryptPayload": true
      }
    }
  ]
}

Best Practices

  1. Use HTTPS - Always use secure endpoints
  2. Authenticate - Protect your webhook endpoints
  3. Validate signatures - Verify webhook origin
  4. Handle retries - Implement idempotency
  5. Set timeouts - Prevent hanging connections
  6. Monitor failures - Track webhook health
  7. Secure secrets - Use environment variables
  8. Test thoroughly - Validate before production