Salesforce Commerce Integrations
Before Writing Code
CRITICAL: Always fetch live documentation BEFORE implementing integrations.
- Web-search: "Salesforce Platform Events developer guide 2026"
- Web-search: "Salesforce Change Data Capture implementation guide 2026"
- Web-search: "Salesforce Named Credentials callout authentication 2026"
- Web-search: "Salesforce Commerce Cloud SCAPI hooks reference 2026"
- Web-search: "Salesforce Commerce Cloud webhooks HMAC verification 2026"
- Web-fetch:
https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/ - Web-fetch:
https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/ - 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.
| Pattern | Platform | Direction | Delivery | Use Case |
|---|---|---|---|---|
| Platform Events | B2B (Apex) | Pub/Sub | At-least-once | Order lifecycle, custom business events |
| Change Data Capture (CDC) | B2B (Apex) | Outbound | At-least-once | Record change sync to external systems |
| Streaming API | B2B (Apex) | Outbound | Push | Real-time record change notifications |
| SCAPI Hooks | B2C (SFCC) | Pre/Post | Synchronous | Intercept API calls (basket, order) |
| Webhooks | B2C (SFCC) | Outbound | At-least-once | Notify external systems of events |
| Outbound Messages | B2B (Workflow) | Outbound | SOAP | Legacy workflow-triggered notifications |
| Job-Based Import/Export | B2C (SFCC) | Bidirectional | Batch | Scheduled file-based data sync |
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 Type | Timing | Can Modify | Example |
|---|---|---|---|
beforePOST | Before API processes request | Request body | Validate inventory before add-to-cart |
afterPOST | After API processes request | Response body | Send order to OMS after placement |
modifyGETResponse | After GET response built | Response body | Add custom attributes to API response |
beforePATCH | Before PATCH processes | Request body | Validate coupon code before applying |
afterPATCH | After PATCH processes | Response body | Log basket modifications |
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
__esuffix (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
ReplayIdto replay missed events
Change Data Capture (CDC) automatically publishes change events when standard or custom object records are created, updated, deleted, or undeleted.
| CDC Header Field | Purpose |
|---|---|
entityName | Object name (e.g., Order, Product2) |
recordIds | List of affected record IDs |
changeType | CREATE, UPDATE, DELETE, UNDELETE |
changedFields | List of field API names that changed |
commitTimestamp | When the change was committed |
transactionKey | Groups changes from the same transaction |
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
| System | B2C Pattern | B2B Pattern |
|---|---|---|
| ERP (SAP, Oracle, NetSuite) | SCAPI hook afterPOST, job-based export | Platform Event, CDC |
| OMS (Order Management) | Webhook order.created, SCAPI hook | Platform Event on Order |
| PIM (Product Information) | Job-based import (XML/CSV) | CDC on Product2 |
| Tax Engine (Avalara, Vertex) | SCAPI hook beforePOST on basket | CartExtension TaxCalculator callout |
| Shipping Carrier (FedEx, UPS) | SCAPI hook for rate shopping | CartExtension ShippingCalculator callout |
| Payment Gateway | SCAPI hook on checkout | Apex callout with Named Credentials |
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.
| Credential Type | Auth Method | Use Case |
|---|---|---|
| Named Credential | Basic, OAuth 2.0, JWT | Apex callouts to external APIs |
| External Credential | OAuth 2.0 Client Credentials | Server-to-server integration |
| Per-User | OAuth 2.0 Auth Code | User-specific external access |
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: Platf