Salesforce integration guide

​

Before you begin

1. Plan scope and owners.
2. Connect Salesforce.
3. Map fields and properties.
4. Define events and goals.
5. Sync intelligence back.
6. Validate end to end.

​

In this guide

• Connection methods and deployment planning
• Requirements and Salesforce permissions
• Partner authentication connector
• API integration
• Webhook integration
• CSV data import
• Warehouse connection
• Data schema and field mapping
• CRM events and conversion goals
• Syncing intelligence back to Salesforce
• Validation and troubleshooting

​

Connection methods and deployment planning

​

Define the deployment scope

​

Requirements and Salesforce permissions

​

Required information

• Salesforce My Domain hostname and organization ID, with production or sandbox clearly identified.
• Authorized Salesforce user with access to the records and fields in scope.
• Stiddle workspace and administrator access to Connectors, Events Manager, Properties and the selected import route.
• Object API names, field API names, custom objects, record types and relationships.
• Stage definitions, MQL and SQL rules, attribution goals, currency and reporting timezone.
• Outbound fields, target objects and Salesforce automation affected by updates.

​

Permission matrix

​

OAuth authorization

​

Partner authentication connector

​

Connect Salesforce

1. Open the correct Stiddle workspace and go to Data → Connectors.
2. Select Sales Channels, find Salesforce, and choose Connect To Stiddle.
3. In Connect Salesforce, enter the Salesforce domain hostname, for example yourcompany.my.salesforce.com. Use the org’s My Domain value, not a Lightning page URL. The Salesforce user menu can help identify the domain.
4. Select Connect Salesforce and authenticate with the Salesforce user approved for the integration.
5. Review the app name and access request, then choose Allow.
6. Return to Stiddle and open Configure. Check that the correct org is connected and review the Last Sync value.
7. Configure record filters and custom mappings before approving a full historical load when the workflow permits it. If connection begins syncing immediately, establish routing and permissions first.
8. Validate records in People Profiles, Companies and Deals, plus Event Logs and Sync Logs.

​

Configure the connection

​

Map custom fields and objects

​

API integration

​

Requirements

​

Extraction and delivery procedure

1. Authorize the Salesforce API client using the org-approved OAuth flow. Confirm the integration user and allowed objects.
2. Inspect each object using the Salesforce sObject Describe resource. Capture field names, types, relationships and operation capabilities.
3. Extract accounts, contacts or leads, opportunities and relationship records. Request only mapped fields.
4. Follow the pagination locator until the query is complete. A synchronous Salesforce query can return up to 2,000 records in a batch, sometimes fewer.
5. Transform each record into the approved Stiddle schema. Preserve Salesforce org ID, object API name, record ID and modification timestamp.
6. Send an initial backfill, then incremental updates using a reliable modification watermark with an overlap window and deduplication.
7. Advance the delivery checkpoint only after the receiving system confirms acceptance under its documented contract. Retain failed records for retry and reconciliation.
8. Handle deleted records, merges and lead conversion through explicitly supported operations rather than treating missing records as deleted.

​

Example delivery envelope

{
  "source": "salesforce",
  "source_org_id": "<salesforce_org_id>",
  "object_type": "Opportunity",
  "record_id": "<opportunity_id>",
  "operation": "update",
  "occurred_at": "2026-10-01T21:00:00Z",
  "idempotency_key": "<org>:<object>:<id>:<version>",
  "properties": {
    "AccountId": "<account_id>",
    "StageName": "Qualification",
    "Amount": 50000,
    "CurrencyIsoCode": "USD"
  }
}

​

Webhook integration

​

Setup using the Stiddle connector instructions

1. Open Data → Connectors → Salesforce → Configure → Webhook API.
2. Obtain the receiver URL, authentication details and current setup instructions for this workspace. Do not copy credentials from screenshots or another workspace.
3. In Salesforce Setup, configure outbound access for the approved receiver. The Stiddle instructions use Remote Site Settings with https://api.stiddle.com as the host. Prefer an approved Named Credential design for managed authentication when supported by the implementation.
4. Deploy the reviewed Apex class and trigger, or the approved Flow and middleware equivalent, in a test environment first.
5. Configure the objects and meaningful field changes that should generate deliveries. The screenshot’s sample watches Opportunity StageName and Amount after update.
6. Send test changes and validate the received payload, linked records and events in Stiddle.
7. Deploy the tested automation, monitor failed deliveries and reconcile against Salesforce periodically.

​

Payload and delivery design

​

Configure and map a webhook endpoint in Stiddle

1. Open the correct workspace and select Data → Webhook, then Add endpoint.
2. Under Events to subscribe, select the event options available for this endpoint. The visible selections include contact.created, contact.updated, contact.upserted, deal.created, deal.updated and deal.closed_won. Order options are also visible but are outside the CRM setup scope.
3. Enter the required Label, using a name that identifies the source, workspace and purpose.
4. Review Webhook URL and use Copy to clipboard. Obtain the workspace’s current value rather than reusing a screenshot URL.
5. Under Secrets, copy the current credential through the approved secret-management process. The displayed header key is x-stiddle-api-key. The modal instructs callers to supply this header and refers to an HMAC-SHA256 payload signature.
6. Use Test import to test the approved payload, then select Next to open Property mapping.
7. Send a test payload from the source, then select Refresh. The mapping dialog states that incoming properties appear after the source fires a webhook.
8. Map each Incoming Key and Incoming Value to an existing Stiddle property. Use search and Add mapping row as needed. The property selector includes CRM, identity and marketing properties; map only fields relevant to the event.
9. Select Save webhook. Review the endpoint’s Enabled status, subscribed event labels, success rate and Last delivery in Active Endpoints. Use Edit to correct its configuration; confirm deletion effects before removing an endpoint.

​

CRM event types shown in the webhook catalog

​

Optional change stream architecture

​

CSV data import

​

Supported types shown in the UI

​

Prepare the files

​

Import procedure

1. Open Data → Import → Import Configuration in the correct workspace.
2. In Import details, enter Import name and select the Event type.
3. In Upload CSV file, drag in the file or use Choose file. Begin with a small test file that follows the selected template.
4. In Map columns to properties, review the CSV Column, Stiddle Property and Include selections. Use Auto-map columns as a starting point, then check every mapping. The UI states that unmapped columns are skipped.
5. Use property search or Load all properties to find destination properties. Use Clear all only when intentionally rebuilding the mapping. Ensure CRM identifiers, relationships, timestamps and monetary values are included where the import supports them.
6. Under Import options, select how existing records are handled. Review the options below before loading production data.
7. Configure Identify imports by. Email is the default matching key; choose a stable alternative key for Companies, Deals, Events and Salesforce records without email.
8. In Select import date, choose the CSV column that represents the record’s created or import date. The UI says this is optional and defaults to import time when unselected. Validate whether this field also controls event occurrence time before using it for historical attribution.
9. Select Preview import, review the results through the available preview, then Start import. Both controls are visible but disabled before a file is configured in the screenshots.
10. Review Import Logs and View history, then inspect the resulting profiles, companies, deals or events. Correct mapping or validation errors before importing the remaining data.

​

Existing record behavior shown in the UI

​

Warehouse connection

​

Requirements and access

​

Configure the dataset

1. Agree the Stiddle warehouse connection mechanism, authentication and network requirements with your Stiddle contact.
2. Create curated views for accounts, contacts, leads, opportunities and contact roles. Include campaign or activity data only when required.
3. Map source columns to the entity schema in Section 8. Keep source_org_id and workspace routing fields in every dataset.
4. Define update timestamps, soft-delete markers, replication timestamps and any retained stage-history table.
5. Validate uniqueness, foreign keys, row counts and timezone conventions before enabling ingestion or queries.
6. Run a test sync or query through the approved Stiddle setup and inspect the results.
7. Agree the refresh schedule and report both upstream replication time and Stiddle processing time.

​

Returning data from the warehouse

​

Data schema and field mapping

​

Common Salesforce property groups

​

Mapping across Salesforce products

​

Contact Group properties

​

CRM Contact properties

​

CRM Account properties

​

CRM Opportunity properties

​

CRM Event properties

​

Recommended integration metadata

​

Example source field mappings

​

Mapping rules

​

Create custom groups and properties

1. Open Data → Properties and select New Property.
2. Enter Property Name and Property ID, keeping the display label and stable key distinct.
3. Select Property Type to match the source value. Common types in the Salesforce groups are STRING, NUMBER, BOOLEAN and DATETIME.
4. Select one or more applicable Property Groups, including custom groups where needed. The same property can be assigned to multiple groups.
5. Add a Description explaining the source product, object, field and business meaning.
6. Under Advanced Options, enable PII property for personally identifying values when appropriate. This hides the property from views where it should not be exposed; it does not define deletion, consent or export policies.
7. Select Save, return to the source mapping and assign the incoming field to the property. Refresh or reload the property list if needed.
8. Validate a source record or event and confirm the property appears with the expected value and type in the intended groups.

​

Additional datasets to evaluate

​

CRM events and conversion goals

​

From source events to attributed outcomes

1. Define the source event. Select the source and trigger, then map its properties and identifiers. The source could be Salesforce or another connected system, a webhook, an API or an import.
2. Associate the event with an individual. Stiddle’s identity graph uses the available identifiers and relationships to map the event to the relevant individual and their profile, connecting the activity to their customer journey.
3. Associate account and opportunity context. Where relevant, Stiddle links the activity to the company account and opportunity using the available CRM relationships. This connects individual activity with account engagement and deal progression.
4. Define a goal for the outcome. Select the event that should count as a conversion or other business outcome. An event contributes to that goal when it matches the goal’s configuration and counting rules.
5. Associate a value and calculate attribution. A goal can carry a value from an event property, such as opportunity revenue, a fixed value or no monetary value. Stiddle uses the associated journey, goal outcomes, value and connected marketing spend to calculate attribution and outcome-based performance metrics.

​

Salesforce opportunity stage example

​

Create a CRM event

1. Open Data → Events Manager and select Create Event.
2. Enter an Event Name and the required Event ID. Use a stable naming convention.
3. Add tags and a description so the GTM team knows what the event means.
4. Select CRM Event as the Event Type and Salesforce as the Source.
5. Select the relevant Property Group, such as CRM Event, then choose the supported trigger in Select Event.
6. Save and test with a source record change. Inspect the resulting entity association, properties and timestamp in Event Logs.

​

Create an opportunity stage event

1. In Create Event, select CRM Opportunity as the event type.
2. Set Source to Salesforce and Property Group to CRM Opportunity.
3. In Select Opportunity Stage, choose the applicable stage or stages.
4. Name the event for its business meaning, such as Open Opportunity or Closed Won, then save.
5. Move a test opportunity into and out of the selected stages and inspect the events and counts.

​

Suggested event plan

​

Configure goals in the current Goals Manager

1. Open Data → Goals Manager. Choose Create Goal, or open an existing goal to edit it.
2. Enter Goal Name and select the matching event under Events. The example selects the Closed Won event for a Closed Won goal.
3. Configure Goal Conversion Value. The UI allows a value property, custom for a fixed dollar value, or no value. The example selects Opportunity Amount. Confirm that the property uses the approved amount field, correct currency and intended revenue definition.
4. Review View through Configuration if view-through attribution is relevant.
5. Under Advanced, review Track previous counted events as goals. The UI describes including matching events counted before the goal was created. Choose this intentionally for historical reporting and validate the resulting date range and counts.
6. Select Save. Review the goal in Goals Manager and test its attributed metrics in the intended report.

​

Syncing intelligence back to Salesforce

​

Configure a destination

​

Record properties and object fields

​

Event history in Salesforce timelines

​

Audiences and membership

​

Account scoring

​

Sync safeguards

​

Validation and troubleshooting

​

Inspect Salesforce sync logs

​

Review batches and changed properties

1. Expand the Salesforce log row for the required entity to open Batch sync details.
2. Review the entity, source, time, rows synced, inserted count and updated count for each batch.
3. Select the linked Inserted or Updated count where available to open the record list. For deal updates, the detail view is labeled Updated Rows – deals.
4. Locate the intended record. The deal list includes Name, platform id, platform account reference, description, stage name and amount. Scroll to inspect any additional fields.
5. Expand the record and review Properties. Compare the Previous and Current values for each property; changed current values can be highlighted.
6. Confirm the expanded detail belongs to the intended Salesforce record using its full source ID. Use the account reference to validate the relationship, and compare the record with the corresponding deal, company or profile in Stiddle.
7. Check Event Logs separately if the update should create a CRM event. Verify the configured goal separately if that event should count as a conversion.

​

Example updated deal with dummy data

​

Acceptance tests

• One Account, two Contacts and one Opportunity preserve their Salesforce IDs and relationships in Stiddle.
• Lead conversion follows the approved identity crosswalk without duplicating a person or losing deal associations.
• A custom amount and stage mapping populate the intended deal fields with correct types and currency.
• Brand or record-type filters include the intended data and exclude another workspace’s records.
• A stage change generates the expected event once; an unrelated update and a retry do not inflate conversion counts.
• CSV or API replay follows the agreed update and deduplication behavior.
• A score or audience change reaches the correct Salesforce field and records its source timestamp.
• Audience exit clears membership under the configured rule.
• A timeline write creates the intended activity, appears to the intended sales user and is not duplicated on retry.
• A simulated permission or delivery failure is visible to the integration owner and can be reconciled.

​

Troubleshooting matrix