Skip to main content

Tracking Atomic Card Response Events in Marketo

Atomic sends Response events back to customer systems when significant activities occur relating to a card. Response events are sent as-they-happen. Response events are sent for the core-subset of card activities, the full set of activities are also tracked as Analytics events.

This pattern is suitable for when Marketo needs to know:

  • that a response event has been sent by Atomic, and
  • key context about that event

This pattern is not suitable for:

  • updating lead profile data/fields as a result of Atomic card actions

What this pattern achieves:

  • Response events and data from within event payloads are available within Marketo as Custom Activities which are visible in the context of individual leads (history of each lead’s activity) and can also be used to build Smart Lists and triggers. For example, a user’s activity of having completed a specific Atomic card by choosing a particular option on that card, might be used to trigger Marketo to tell Atomic to create another follow-on card, or take some other campaign action.

Known limitations:

  • Marketo only permits data values from within a Custom Activity to be used/accessed within a Campaign Flow step in certain scenarios
  • Marketo only allows up to 10 Custom Activity Types, and up to 20 Custom Fields per Custom Activity type which means you need to think carefully about how to structure the Custom Activity Types and Custom Fields, especially when planning to track many different Atomic cards over time.
  • Custom Fields within Custom Activity Types cannot contain objects, so Atomic cards response events will need to consider how to map response payload properties nicely

Implementing this pattern involves:

  1. Configuring Marketo to expect response events from Atomic by defining one or more Custom Event Types within Marketo
  2. Configuring cards in Atomic to send relevant response payloads in a JSON structure that can be received by Marketo
  3. Sending Atomic responses to Marketo’s Lead Database – Activities Controller API via POST to the /rest/v1/activities/external.json API endpoint

1. Configure Marketo to expect response events from Atomic by defining one or more Custom Event Types within Marketo​

Work out what Custom Activity Types are needed​

  • Keep it simple by adding only one custom activity type, named: “Atomic Card Event”
  • Add custom fields which can be used to collect additional context about the event, e.g.
    • “Card Name” (String) Expected value: Card template name in Atomic E.g. “Onboarding Step 1”
    • “Activity Type” (String) Expected value: Type of response event E.g. “card-completed”
    • “Action Detail” (String, Optional) Expected value: Kind of action the user took E.g. “acknowledged” Tip: Instead of using different details for each and every card button/scenario, consider developing some shorthand terms which you can reuse in different situations, we can help with this.
  • There’s no need to add timestamp or id, these are captured by default.

Configure Custom Activity Types in Marketo​

Can be done either in “Admin” or configure via API

Configure Custom Activity Types in Marketo​

Docs here

  • Use Postman, or similar, to send a test
  • Document your example API request for use in the next stage of implementing this pattern

2. Configure cards in Atomic to send relevant response payloads in a JSON structure that can be received by Marketo​

Follow the steps below for each card, and each response event that you wish to track in Marketo

Review your card template to ensure action buttons are set up correctly​

  • For every action button on the top-level of your card, and within your subview, review the element properties. Each button should be configured to send a JSON object using this pattern: {“actionDetail”:”[relevantDetail]”} e.g. {“actionDetail”:”acknowledged”}, {“actionDetail”:”acceptedOffer”}, or {“actionDetail”:”redirectedToUrl”}

Verify your changes​

Verify your changes by sending yourself some test cards, responding, and inspecting your responses within the card log

3. Send Atomic responses to Marketo’s Lead Database – Activities Controller API via POST to the /rest/v1/activities/external.json API endpoint​

Configure Atomic to send response events to Marketo in a format Marketo can handle​

  • Create a Credential in the Configuration > Integrations > credentials screen, using the API credentials document by Marketo.
  • Create a new webhook subscription in the Configuration > Webhook Subscriptions and choose the cards and events you're interested in sending to Marketo. Select the credential you created in the previous step
  • Select ‘Edit payload mapping’
  • Paste the example API request payload from the previous stage into the “Sample payload” input
  • Map the relevant response properties into the payload destined for Marketo
  • Save and send a test

Verify custom activities are being received in Marketo​

  • Confirm custom activities are showing up in Marketo, and can be seen/used in all the expected places:
  • Tracking against a leads record
  • Available in Smart List
Last updated on