Webhook integration

The webhook integration sends an HTTP request to a URL of your choice whenever a lead is submitted or a guide is completed. This is the most flexible integration — it works with any service that accepts HTTP requests, including Zapier, Make (Integromat), n8n, or your own backend. The webhook integration is a Pro feature.

Setting up a webhook

Open a guide in the editor and switch to the Integrations tab. Find the Webhook card, toggle it on, and configure these fields:

• Webhook URL — The endpoint that will receive the data. Must be a valid HTTPS URL.
• Method — The HTTP method: POST (default), PUT, or PATCH.
• Trigger — When to fire the webhook: Lead Submitted (fires when a visitor submits a lead form) or Guide Completed (fires when a visitor reaches the results page, whether or not a lead form was submitted).
• Custom Headers — Optional key-value pairs added to the HTTP request. Use these for authentication tokens, API keys, or any headers your endpoint requires.

Each guide has its own webhook configuration. You can point different guides to different endpoints, use different triggers, or send different headers.

JSON payload

The webhook sends a JSON body with the following structure:

{
  "event": "lead_submit",
  "timestamp": "2025-01-15T14:30:00+00:00",
  "guide_id": 42,
  "guide_title": "Find Your Perfect Laptop",
  "session_id": "abc123def456",
  "selections": [
    {
      "step_title": "What's your budget?",
      "selection": "$500–$1000"
    },
    {
      "step_title": "Primary use?",
      "selection": "Work & Productivity"
    }
  ],
  "result_ids": [101, 205, 318],
  "lead": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1 555-0123",
    "privacy_consent": "yes"
  }
}

• event — Either lead_submit or guide_complete, depending on your trigger setting.
• timestamp — ISO 8601 formatted time of the event.
• guide_id / guide_title — The guide that triggered the webhook.
• session_id — The unique session identifier for this visitor journey.
• selections — An array of all selections the visitor made, each with the step title and chosen label.
• result_ids — An array of WordPress post IDs that matched the visitor’s filters.
• lead — Only present for lead_submit events. Contains all submitted form fields with their field names as keys.

Custom headers

Click Add Header to add key-value pairs. Common use cases:

• Authorization — Bearer your-api-token for token-based auth.
• X-API-Key — API keys for services that use custom header authentication.
• X-Webhook-Secret — A shared secret your endpoint can verify to ensure the request came from GuideForms.

The Content-Type: application/json header is always sent automatically — you don’t need to add it.

Testing

Use the Test Connection button in the webhook settings to send a sample request to your endpoint. This sends a test payload so you can verify your URL is reachable and your endpoint handles the data correctly before going live.

Webhook logging

Every webhook delivery is logged. The log records the request URL, HTTP status code, response body, and whether the delivery succeeded or failed. If a delivery fails, the queue will retry it up to 3 times with increasing delays (see Integrations Overview for retry details).

Security

GuideForms includes SSRF (Server-Side Request Forgery) protection — webhook URLs pointing to internal/private IP ranges are blocked. Only publicly reachable HTTPS endpoints are allowed. The request timeout is set to 30 seconds.

Using with automation platforms

Webhooks work out of the box with popular automation tools:

• Zapier — Create a Zap with “Webhooks by Zapier” as the trigger. Use the “Catch Hook” event and paste the webhook URL into GuideForms.
• Make (Integromat) — Add a “Custom Webhook” module as the trigger. Copy the generated URL into GuideForms.
• n8n — Add a “Webhook” node and set it to accept POST requests. Use the generated URL.

After the first real webhook fires, these platforms auto-detect the JSON structure and let you map fields to subsequent actions (send email, create spreadsheet row, update CRM, etc.).

Next steps

• Integrations Overview — Queue processing, retries, and general integration concepts.
• FluentCRM — Sync leads directly to FluentCRM contacts.
• Leads — How lead data is captured and stored.