Marketing Cloud Custom Activities

Marketing Cloud Custom Activities

This skill activates when a practitioner needs to build or troubleshoot a custom activity, custom split activity, or custom entry source for Marketing Cloud Journey Builder using the three-part framework: config.json (application extension definition), customActivity.js (Postmonger-based UI messaging), and a publicly hosted HTTPS web application with REST callback endpoints.

Before Starting

Gather this context before working on anything in this domain:

• Installed Package access: Confirm the Marketing Cloud account has an Installed Package (Setup > Apps > Installed Packages) with an App Extension of type "Journey Builder Activity" already created or ready to create. The package provides the client ID and secret needed for API auth.
• Hosting infrastructure: The custom activity UI and callback endpoints must be served over HTTPS from a publicly reachable host. Journey Builder will refuse to load an HTTP-only iframe. Confirm the hosting environment (Heroku, AWS, Azure, etc.) and that TLS is provisioned.
• Common wrong assumption: Practitioners often assume the execute endpoint can return custom JSON payloads with a 200 status. Journey Builder only checks for HTTP 200 to advance the contact; any non-200 response causes the contact to error out of the journey regardless of the response body.
• Limits and constraints: The execute endpoint must respond within the configured timeout window (default 30 seconds; configurable per activity). Long-running operations must be made asynchronous — accept the request, enqueue the real work, and return 200 immediately. Journey Builder does not retry on timeout; the contact errors out.

Core Concepts

1. Three-Part Framework

A custom Journey Builder activity has three required components that must work together:

config.json is the application extension definition registered in the Installed Package. It declares the activity's endpoints (execute, save, publish, validate), the configurable arguments schema (what data the journey canvas passes to the activity), metaData including the activity icon, and for custom splits, the outcomes array defining each branch key and label. Journey Builder reads this file at design time to render the activity on the canvas and at runtime to invoke the correct endpoint.

customActivity.js runs in the activity's configuration iframe inside Journey Builder. It uses the Postmonger library — a cross-frame messaging adapter — to communicate with the Journey Builder host application. The script must listen for the ready event before calling any trigger: methods. Key events include requestedSchema (returns the journey entry event schema), requestedData (returns current activity arguments), requestedInteractionDefaults (returns journey-level defaults), and updatedActivity (fired when the practitioner saves activity configuration in the canvas).

Hosted web app is the HTML/JavaScript application served over HTTPS that Journey Builder loads in an iframe when a practitioner opens the activity's configuration panel. It hosts customActivity.js and any UI components for configuring the activity arguments. This app also exposes the REST callback endpoints (execute, save, publish, validate) that Journey Builder calls at runtime and during journey activation.

2. Execute Endpoint and JWT Security

When a journey contact reaches a custom activity step, Journey Builder POSTs to the configured execute URL. The POST body contains the contact's data (from the entry event schema) and journey context metadata. The request header includes a JWT (JSON Web Token) signed with the Installed Package secret. The receiving endpoint must verify this JWT before processing the request — failure to do so allows any caller to trigger the endpoint. After verification and processing, the endpoint must return HTTP 200 within the timeout. For custom splits, the 200 response body must contain a JSON object with a branchResult key matching one of the outcome keys defined in config.json.

3. Custom Splits and Outcome Keys

A custom split activity routes contacts to different journey branches based on logic in the execute endpoint. Outcomes are declared in config.json under metaData.outcomes as an array of objects, each with a key (the identifier the execute endpoint returns in branchResult) and a label (the display name shown on the Journey Builder canvas branch connector). The execute endpoint determines which branch to use and returns the appropriate key. If the returned key does not match any declared outcome, the contact errors out.

4. Postmonger Event Sequence

The Postmonger library enforces a strict initialization sequence. The customActivity.js must:

1. Instantiate the Postmonger session: var connection = new Postmonger.Session()
2. Register listeners for Journey Builder events before calling any trigger methods
3. Listen for 'ready' — only after this event fires is the session initialized and safe to call connection.trigger('requestSchema')
4. Call connection.trigger('ready') to signal to Journey Builder that the activity UI has loaded

Skipping the ready handshake or calling trigger:requestSchema before ready fires causes silent failures where the schema is never populated in the activity's UI.

Common Patterns

Pattern: Standard Custom Activity with Async Execute

When to use: The activity calls an external API or performs work that might exceed a few seconds.

How it works:

1. Execute endpoint receives the POST from Journey Builder
2. Validate the JWT in the Authorization header using the Installed Package secret
3. Enqueue the real work (e.g., push to a queue, write to a database) — do not perform it synchronously
4. Return HTTP 200 immediately
5. A background worker processes the queued work asynchronously

Why not the alternative: Performing the real work synchronously risks exceeding the 30-second timeout. Journey Builder does not retry on timeout; the contact errors out permanently for that journey activation.

Pattern: Custom Split with Multiple Outcome Branches

When to use: The activity needs to route contacts to different journey paths based on a condition (e.g., loyalty tier, purchase history, API response).

How it works:

1. Declare outcomes in config.json metaData.outcomes:

   "outcomes": [
     { "key": "high_value", "label": "High Value" },
     { "key": "standard", "label": "Standard" },
     { "key": "at_risk", "label": "At Risk" }
   ]
   

2. Execute endpoint evaluates the contact and returns:

   { "branchResult": "high_value" }
   

3. Journey Builder routes the contact to the branch connector whose key matches branchResult

Why not the alternative: Using a Decision Split activity requires data to already be in a Data Extension field. Custom splits allow real-time API-based routing that is not pre-stored in SFMC.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Register the App Extension — In Marketing Cloud Setup, create or open an Installed Package. Add a new Component of type "Journey Builder Activity." Set the Name, description, and Endpoint URL (the base URL where config.json will be served). Note the client ID and client secret for JWT validation.

2. Author config.json — At the endpoint base URL, serve a config.json that defines: name, fullName, workflowApiVersion (set to 1.1), metaData (icon, category, outcomes for splits), configurationArguments (schema for the data the activity stores), userInterfaces.configModal (URL to the hosted web app), and endpoints (execute, save, publish, validate URLs). Validate against the Journey Builder Activity Config reference docs.

3. Build the hosted web app — Create an HTTPS-accessible web application. Include postmonger.js from the Postmonger library. In customActivity.js, initialize the Postmonger session, register all event handlers (ready, requestedSchema, requestedData, requestedInteractionDefaults, updatedActivity), then trigger ready to complete the handshake. Implement the UI to collect and display configurationArguments values.

4. Implement execute endpoint with JWT verification — Build the server-side route at the configured execute URL. On each POST: extract the JWT from the Authorization: Bearer <token> header, verify the signature using the Installed Package secret (HS256 or RS256 depending on version), then process the contact data. For custom splits, determine the correct branch and return { "branchResult": "<outcome_key>" } with HTTP 200. For standard activities, return HTTP 200 with any body.

5. Implement save, publish, and validate endpoints — Journey Builder calls these during canvas design and journey activation. save is called when the practitioner saves activity config (return 200 to accept). publish is called when the journey activates (return 200 to confirm the activity is ready). validate is called to check if activity configuration is complete (return 200 with a validation result object).

6. Test end-to-end in a test journey — Create a journey in a sandbox/test Marketing Cloud BU using the custom activity. Use a small test audience. Verify contacts flow through the activity, check journey activity logs for errors, and confirm any external side effects occurred correctly.

7. Verify JWT validation and HTTPS — Confirm the execute endpoint rejects requests without a valid JWT (return 401 or 403). Confirm all endpoints are HTTPS. Confirm no HTTP fallback is allowed.

Review Checklist

Run through these before marking work in this area complete:

• config.json is served over HTTPS and is valid JSON with all required keys (name, workflowApiVersion, metaData, endpoints, userInterfaces)
• customActivity.js listens for ready before calling any connection.trigger() methods
• Execute endpoint verifies the JWT from the Authorization header before processing
• Execute endpoint returns HTTP 200 within 30 seconds (or configured timeout); long operations are enqueued asynchronously
• For custom splits: all outcome keys in branchResult responses exactly match keys declared in config.json metaData.outcomes
• All URLs in config.json (userInterfaces, endpoints) use HTTPS
• save, publish, and validate endpoints are implemented and return HTTP 200
• Tested with a real contact in a test journey; journey activity logs show no errors

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Non-200 response errors the contact permanently — Any HTTP response other than 200 from the execute endpoint causes Journey Builder to mark that contact's journey activation as errored. The contact does not get a retry and does not advance. This includes 201, 202, 204, and any 4xx/5xx. Return exactly HTTP 200.

2. Postmonger ready event must fire before any trigger calls — If customActivity.js calls connection.trigger('requestSchema') before Journey Builder fires the ready event, the call is silently dropped. The schema is never returned and the UI has no field mappings. Always register listeners first, then call connection.trigger('ready') and wait.

3. config.json must be reachable without authentication — Journey Builder fetches config.json at design time from the URL registered in the App Extension. If the endpoint requires authentication or returns a non-200, the activity will fail to load on the canvas. Serve config.json as a public, unauthenticated GET endpoint.

Output Artifacts

Related Skills

• admin/journey-builder-administration — Use when the issue is with the Journey Builder canvas, entry source configuration, journey settings, or standard activity setup rather than custom activity code
• apex/marketing-cloud-rest-api — Use when working with the Marketing Cloud REST API for data operations outside of the Journey Builder custom activity framework