Sf Integrations

Salesforce Commerce Integrations

Before Writing Code

CRITICAL: Always fetch live documentation BEFORE implementing integrations.

1. Web-search: "Salesforce Platform Events developer guide 2026"
2. Web-search: "Salesforce Change Data Capture implementation guide 2026"
3. Web-search: "Salesforce Named Credentials callout authentication 2026"
4. Web-search: "Salesforce Commerce Cloud SCAPI hooks reference 2026"
5. Web-search: "Salesforce Commerce Cloud webhooks HMAC verification 2026"
6. Web-fetch: https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/
7. Web-fetch: https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/
8. Web-fetch: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_named_credentials.htm

Integration APIs, security requirements, and event schemas change across Salesforce releases. Verify hook types, event schemas, authentication patterns, and signature algorithms against current docs.

Conceptual Architecture

Event-Driven Architecture Overview

Salesforce Commerce supports multiple event-driven integration patterns across B2C and B2B platforms.

B2C Integration Patterns

SCAPI Hooks provide pre/post processing on API calls. Hooks are disabled by default and must be explicitly enabled in Business Manager. Hook scripts live in cartridges and are configured via hooks.json.

Hook scripts follow the dw.ocapi.shop.[resource].[hookType] naming convention and are registered in the cartridge's hooks.json file.

Webhooks deliver event notifications to external HTTP endpoints. Events include order.created, order.updated, inventory changes, and catalog updates. Webhook configuration is managed via the Data API.

Job-Based Integration uses scheduled scripts for bulk data sync via IMPEX directory (WebDAV or SFTP), parsing XML/CSV files and updating Commerce Cloud objects within Transaction.wrap().

B2B Integration Patterns

Platform Events are custom publish/subscribe events defined in Salesforce Setup. Publishers use EventBus.publish() from Apex; subscribers use Apex triggers on the event or external CometD/Pub/Sub API clients. Key characteristics:

• Defined as custom objects with __e suffix (e.g., OrderShipped__e)
• Support custom fields (Text, Number, DateTime, etc.)
• Published outside of transaction rollback scope (fire even if transaction fails when using publish after commit)
• Subscribers can set ReplayId to replay missed events

Change Data Capture (CDC) automatically publishes change events when standard or custom object records are created, updated, deleted, or undeleted.

Enable CDC for specific objects in Setup > Change Data Capture. Not all objects support CDC -- verify in documentation.

Outbound Messages are SOAP-based notifications triggered by workflow rules. The receiver must expose a SOAP endpoint and return an Ack: true response. These are legacy; prefer Platform Events for new integrations.

External Services provide declarative integration via OpenAPI specs imported into Salesforce, generating Apex classes automatically. Useful for no-code/low-code integration via Flow Builder.

Common Integration Targets

HMAC Verification

Incoming webhooks must be verified using HMAC signatures before processing. The sender computes an HMAC-SHA256 digest of the payload using a shared secret and includes it in a header (e.g., X-DW-Signature for Commerce Cloud). The receiver recomputes the digest and compares using constant-time comparison to prevent timing attacks. Key points:

• Always use SHA-256 (or the algorithm specified in current docs)
• Use constant-time string comparison (not ===) to prevent timing side-channels
• Reject requests with missing or invalid signatures immediately (return 401)
• Rotate webhook secrets periodically and support dual-secret rotation windows

Idempotency

Webhooks and Platform Events deliver at-least-once, meaning duplicates are possible. Every event handler must be idempotent:

• Use the unique event ID (e.g., event_id, ReplayId) as a deduplication key
• Check a persistent store (database table or cache like Redis) before processing
• Skip duplicates with a 200 OK response (not an error)
• Set a reasonable TTL (24-48 hours) for the deduplication window
• For database-backed deduplication, use a unique constraint on the event ID column

Named Credentials

Named Credentials manage external service authentication declaratively in Salesforce Setup. They handle OAuth 2.0 token refresh, basic auth, and custom headers automatically. Always use callout:CredentialName/path in Apex HTTP requests -- never hardcode API keys or secrets.

Error Handling and Retry Strategy

• Distinguish retryable (5xx, timeout, network error) from non-retryable (4xx) errors
• Implement exponential backoff: delay = 2^attempt * base_delay, max 3-5 attempts
• Add jitter (random component) to prevent thundering herd on retries
• Use a dead letter queue (DLQ) for messages that exceed max retries
• Log all integration activity with correlation IDs for end-to-end tracing
• Platform Events support replay: subscribers can replay missed events using ReplayId
• For B2C webhooks: respond with 200 OK quickly, then process asynchronously

Code Examples

Pattern: Platform Event publisher skeleton

OrderShipped__e event = new OrderShipped__e(
    OrderId__c = orderId
);
Database.SaveResult sr = EventBus.publish(event);
// Fetch live docs for EventBus.publish error handling

Pattern: SCAPI hook module skeleton

exports.beforePOST = function(basket, requestBody) {
    // Fetch live docs for SCAPI hook signatures
};
module.exports.afterPOST = afterPOST;

Pattern: CDC subscriber concept

// Subscribe to /data/OrderChangeEvent via CometD
// Fetch live docs for CDC event schema and replay

Best Practices

Event-Driven Design

• Decouple systems with async messaging (Platform Events, webhooks)
• Design for eventual consistency -- avoid synchronous cross-system calls
• Add new consumers without changing publishers
• Use CDC for record-change sync; Platform Events for custom business events

Security

• Always validate HMAC signatures before processing webhooks
• Use constant-time comparison to prevent timing attacks
• Use Named Credentials for all outbound callouts -- never hardcode secrets
• Rotate webhook secrets and API credentials on a regular schedule

Reliability

• Implement idempotency on every event handler using unique event IDs
• Use exponential backoff with jitter for retries
• Route failed messages to a dead letter queue for manual inspection
• Monitor integration health: success rate, latency, error rate, DLQ depth

Observability

• Structured JSON logging with correlation IDs across all integration points
• Track metrics: requests total, error count, duration histogram
• Set alerts for sustained failure rates or latency spikes
• Document all integration points, API contracts, and runbooks

Fetch the latest Salesforce Platform Events guide, CDC guide, SCAPI hooks reference, and Named Credentials documentation for exact event schemas, hook signatures, and authentication configuration before implementing.