Integrations — Streaming XM Cloud Forms to Salesforce with Sitecore Connect

On most XM Cloud builds, “Get these form fills into Salesforce” lands in the backlog early. The good news is that XM Cloud Forms has built-in webhook support—no custom code needed to get form data flowing to external systems.

The architecture is straightforward:

• Build forms visually in the XM Cloud Forms Builder (no backend code required).
• Configure a webhook in the Forms app that points to Sitecore Connect.
• Sitecore Connect receives the payload and pushes it to Salesforce (or any other system).

This post walks through the complete setup: creating forms, configuring webhooks, building the Connect flow, mapping fields to Salesforce, and handling the edge cases that come up in real projects.

Architecture at a glance

Key point: XM Cloud Forms does not store submission data. The webhook fires on every submission and passes the payload through to your configured endpoint. If Connect (or your endpoint) is down, that submission is lost unless you add resilience upstream.

Step 1 — Build the form in XM Cloud Forms Builder

XM Cloud includes a visual Forms Builder accessible from the Sitecore Cloud Portal. No custom development needed for basic lead capture forms.

Available field types

The Forms Builder supports:

• Input fields: Email, Phone, Short Text, Long Text, Number, Date
• Selection: Dropdown, Multi-select, Radio buttons, Checkbox, Checkbox Group
• Validation: reCAPTCHA, Terms & Conditions
• Layout: Text blocks, Spacers, Images, Social Media buttons
• Hidden fields: For passing static values (UTM parameters, form IDs, etc.)

Creating a “Contact Us” form

1. Open the Forms app from the Sitecore Cloud Portal launchpad.
2. Click Create Form and select a layout template.
3. Add fields by dragging from the palette:
   • Email (required, with validation)
   • First Name, Last Name (required)
   • Company, Job Title (optional)
   • Phone (optional)
   • Message (Long Text, optional)
4. Add a reCAPTCHA field to prevent spam.
5. Add a Terms & Conditions checkbox if needed for consent tracking.

Naming fields for downstream mapping

This is important: rename your field identifiers from the auto-generated names (like text_66ee8) to something meaningful (like firstName, company). These identifiers become the JSON keys in the webhook payload, and clear names make Sitecore Connect mapping much easier.

To rename:

1. Select the field.
2. In the Settings panel, find the Field Name or Identifier setting.
3. Use camelCase names that match your target system conventions.

Step 2 — Configure a webhook in XM Cloud Forms

Before you can activate a form, you must configure a webhook. XM Cloud Forms requires every form to have a destination for its data.

Creating the webhook

1. In the Forms app, go to the Webhooks tab.
2. Click Add Webhook.
3. Configure:
   • Name: Something descriptive like Salesforce-Connect-Prod
   • URL: The Sitecore Connect webhook endpoint (we’ll create this next)
   • Authentication: Choose based on your Connect setup:
     • None — for testing only
     • API Key — adds a header like x-api-key: your-key
     • Basic Auth — username/password in Authorization header
     • OAuth 2.0 — for production integrations requiring token auth
4. Save the webhook.

Attaching the webhook to your form

1. Open your form in the editor.
2. Go to Settings.
3. Under Webhook, select the webhook you just created.
4. Configure the Submit Action:
   • Redirect to URL — send users to a thank-you page
   • Show message — display an inline confirmation
   • None — for AJAX-style submissions where your head handles the UX

Understanding the webhook payload

When a form is submitted, XM Cloud sends a JSON payload to your webhook URL. The structure looks like this:

{
  "formId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "formName": "Contact Us",
  "submittedAt": "2025-09-10T14:32:00.000Z",
  "fields": {
    "email": "jane.doe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Acme Corp",
    "jobTitle": "Head of IT",
    "phone": "+1 555-123-4567",
    "message": "I'd like to learn more about your enterprise plans.",
    "marketingConsent": true
  },
  "metadata": {
    "pageUrl": "https://www.example.com/contact",
    "language": "en",
    "siteName": "acme-main"
  }
}

The exact structure depends on your field names and any hidden fields you’ve added. Use the Test Webhook feature in the Forms app to see exactly what payload your form generates.

Testing before go-live

The Forms Builder includes a Test Webhook button that:

• Sends a sample payload to your configured URL
• Shows you the exact JSON being sent
• Includes a "test": true flag so you can filter test submissions downstream

Always test before activating the form. Once activated, forms cannot be edited (you’d need to create a new version).

Step 3 — Set up the Sitecore Connect webhook trigger

Now we need Sitecore Connect to receive the webhook and process it.

Creating a new recipe

1. Log into Sitecore Connect (via the Cloud Portal).
2. Create a new Project (e.g., XM Cloud Integrations) or use an existing one.
3. Create a new Recipe.
4. For the trigger, select Webhook (or HTTP Webhook depending on your Connect version).
5. Connect generates a unique webhook URL — copy this.

Configuring the trigger

1. Give the trigger a name like xmcloud_form_submission.
2. Set the expected payload format to JSON.
3. If you want authentication:
   • Configure an API key requirement in Connect
   • Add the same key to your XM Cloud webhook configuration
4. Paste a sample payload (from your Form Builder test) so Connect can parse the schema.

Completing the webhook loop

1. Go back to XM Cloud Forms.
2. Edit your webhook configuration.
3. Paste the Connect webhook URL.
4. Add authentication headers if configured.
5. Test the webhook again — you should see the test event appear in Connect’s run history.

Step 4 — Connect to Salesforce

With the webhook trigger working, add a Salesforce connection to your recipe.

Setting up the Salesforce connector

1. In your Connect recipe, add a new action after the trigger.
2. Select Salesforce from the connector list.
3. Authenticate:
   • You’ll need a Connected App in Salesforce with OAuth credentials
   • Grant permissions for Lead/Contact creation and updates
   • The integration user needs appropriate object and field-level security

Building the flow logic

A typical form-to-Salesforce flow looks like this:

Step-by-step recipe configuration

Step 1: Validate required fields Add a condition to check that fields.email exists and is not empty. Exit early if validation fails.

Step 2: Search for existing Lead Use Salesforce’s “Search records” action:

• Object: Lead
• Filter: Email equals {{fields.email}}

Step 3: Branch based on search result

• If record found → Update Lead
• If not found → Create Lead

Step 4: Map fields Whether creating or updating, map the webhook payload to Salesforce fields:

Step 5: Log the activity Create a Task linked to the Lead:

• Subject: Form submission: {{formName}}
• Description: Include the full message and context
• Status: Completed
• WhoId: The Lead ID from the create/update step

Step 5 — Handle edge cases and errors

Duplicate submissions

Users sometimes double-click submit buttons. To handle this:

1. Add a hidden field to your form with a unique submission ID (though note: hidden fields in XM Cloud Forms only support static values, so you may need to generate this client-side and pass it in).
2. Store this ID in a custom Salesforce field like Integration_Id__c.
3. In Connect, search by this ID before creating new records.

Alternatively, rely on the email-based deduplication in Step 4 — updating existing Leads rather than creating duplicates.

Webhook failures

If Sitecore Connect is unreachable when a form is submitted, that submission is lost. XM Cloud Forms does not retry failed webhooks.

For high-value forms, consider:

1. Adding a queue between the form and Connect (Azure Service Bus, AWS SQS)
2. Using a webhook relay service like Hookdeck that provides retry logic
3. Monitoring Connect for failed runs and setting up alerts

Salesforce API errors

Common issues:

• Required field missing — ensure all Salesforce required fields have values or defaults
• Validation rule failures — map data to match Salesforce validation rules
• API limits — batch high-volume forms or implement throttling

In Connect, add error handling steps that:

• Log the full error message
• Optionally send an alert email
• Store failed payloads for manual review

Step 6 — Known limitations and workarounds

XM Cloud Forms is still evolving. Here are current limitations and how to work around them:

One submit action per form

You can’t natively send to both a CRM and an email notification.

Workaround: Have Connect fan out to multiple destinations — the webhook sends to Connect, and Connect triggers both Salesforce creation and an email notification.

No dynamic hidden field values

Hidden fields only accept static values. You can’t pull dynamic data from Sitecore items.

Workaround: Pass dynamic values (like UTM parameters) from the client-side JavaScript into regular hidden form fields, or add them to the page URL and configure the webhook to capture referrer data.

No file uploads

Webhooks can’t handle file attachments.

Workaround: For forms requiring file uploads, use a custom form component in your Next.js head that posts to your own API, which then handles file storage and sends metadata to Connect.

Forms can’t be edited after activation

Once activated, a form is locked.

Workaround: Plan forms carefully before activation. For changes, create a new form version and update your page to reference it.

No conditional logic

You can’t show/hide fields based on other field values.

Workaround: Create separate forms for different scenarios, or handle conditional logic in your Next.js head with a custom form component.

Observability: knowing it’s working

Set up monitoring so you know when things break:

In Sitecore Connect

• Review run history regularly
• Set up alerts for failed runs
• Monitor recipe execution times for performance issues

In Salesforce

• Create a report showing Leads created in the last 7 days with source = your form
• Set up alerts if the daily count drops unexpectedly

End-to-end testing

Periodically submit a test form and verify:

1. The webhook fires (check Connect run history)
2. The Lead appears/updates in Salesforce
3. The Task is created with correct details
4. Any notification emails are sent

Useful links

• XM Cloud Forms documentation
• Working with webhooks in XM Cloud
• Sitecore Connect documentation
• Salesforce REST API
• Understanding Webhooks in XM Cloud Forms (Fishtank)
• XM Cloud Forms Webhooks Integration (Kayee)
• Integrating XM Cloud Forms with Sitecore Connect

Related posts

• Integrations — Series overview
• Integrations — Vercel routing and microfrontends for XM Cloud
• Integrations — Reviewing XM Cloud pull requests with coding agents
• AI-Powered Stack — Series overview