Skip to main content

Action Flow Triggers

There are two ways to start an Action Flow:

Just need a quick guide on creating an Action Flow? Head to the creating Action Flows article.

Test events vs. Live events​

tip

Before you're ready to trigger Action Flows with an intent to send live cards and record production ready data, you're likely to want to runs some tests. Tests might be as simple as sending a test card to yourself to review on the Atomic Connect demo app, or as advanced as sending test API events and running an entire Action Flow as a test.

The testing article provides detailed information on testing Action Flows, but here in the context of understanding Triggers, there are some key concepts worth highlighting:

  • Atomic enables you to send test events and generate test cards. When you do, the analytics and card instances created clearly identify as tests, so you can identify, and potentially ignore or remove them.
  • You can adjust configuration settings for each Atomic environment to deal with test data in analytics to meet your needs
  • When sending a test from within the Action Flow editor, the cards and analytics will automatically be marked as tests, and tests will always use the current draft version of your card templates
  • When sending test API trigger requests to the unique API trigger endpoint for your Action Flow, you should use the /test path, not the /start path.
  • When sending test requests to a configured Webhook trigger, you should ensures the trigger is in Test mode
  • The Test Action Flow sender tool is available for when you need to send a batch of test events, but prefer not to use an API request.
  • Only test users accounts can be sent test Action Flows, or will receive test cards. Attempts to target a User Id not recognized either as a Workbench Member User Id, or a manually created External test user will be ignored. This is a safeguard to prevent draft cards and flows being sent to live User Ids.

Dynamic triggers​

Atomic supports the following dynamic Action Flow triggers:

API triggers​

Every Action Flow is given a unique URL that can be used to send test and live triggers. These requests are sent to the Action Flow API, and are authenticated using the OAuth2 Client Credentials method, using credentials configured via the Workbench, or managed via the Credentials API.

  • API triggers need to follow the Action Flow API requirements, including the shape of the request body.
  • Requests will identify target user IDs, or use other supported methods for identifying users already within the Atomic platform
  • Requests should be batched when large volumes are expected and where any variables supplier are unique per target user ID
  • If variables aren't used, or can be shared between target users in a single request, a request can target a list of user IDs.

When to consider an API trigger​

API triggers are most commonly used in situations where:

  • You have the ability to control the requests being made to Atomic from your external system
  • You want requests to use the OAuth2 request authentication method
  • You have the need/ability to batch requests
  • You're testing using tools like Insomnia, Postman, or your other development tools
info

Every Action Flow contains an API Trigger. You can ignore it if you don't need it, but it cannot be removed from the configuration.

Webhook triggers​

Webhook triggers enable incoming webhook requests to trigger Action Flows.

  • When adding a Webhook trigger to your Action Flow, you'll be provided a unique URL. You'll configure your sending system to POST requests to this endpoint.
  • At a minimum, the incoming request body must contain a value for the user id you plan to target in Atomic.
  • If the incoming request contains other variables or personalization data, this can also be mapped so it overrides the default values of corresponding context variables you've configured.

When to consider a Webhook trigger​

Webhook triggers are most commonly used in situations where:

  • You're working with a cloud platform that supports webhooks, but
  • The triggering event occurs in a system that can’t make OAuth2 requests to the Atomic API, or
  • You don’t have full control over the shape of the request payload body being sent to Atomic from the initiating system

These situations are common when working in another cloud system, such as a Marketing Automation or CRM platform.

Mapping incoming webhook payloads​

When configuring your Webhook trigger, a mapping option enables you to describe how Atomic should extract relevant data from webhook requests and transform it into a shape Atomic can use to trigger your Action Flow.

  • With the Webhook trigger selected on the canvas, click Edit payload mapping
  • The first step of the mapping process involves sending an event to the Webhook URL using a POST or PUT request, and capturing the body of that request to use as an example while creating your mapping, or pasting/writing an example payload if capturing a real event is not feasible.
  • Once you have a sample payload, you can either write a mapping using JavaScript, or use the basic no-code mapping option to map the target user ID and any values you will pass through as variables.
  • If your incoming webhook request body will already be in the shape required by Atomic, you don't need to transform it

After mapping, the shape of your request body should conform to the following schema:

{
  // Array of target user ids is required
  targetUserIds: ["76DHG129387"],

  // All other properties are optional
  // Idempotency key
  flowInvocationId: "6fad5d419180",
  // Key/value pairs you will pass into variables in the Action Flow
  variables: {
    variable_name: "variable value",
    another_variable_name: "..."
  },
  notificationDetail: {},
  metadata: {}
}

Test the webhook trigger by sending a request to the webhook URL​

To test your webhook trigger, you can send a webhook to your new Webhook trigger URL which will also trigger an Action Flow. Make sure the structure of the body of your request matches the sample payload used when creating the Connector trigger.

Note: If you want to send the test card to yourself, ensure the value of the targetUserId in your mapped payload is your own user id.

tip

Remember to check that your Webhook connector is in Test mode while testing, and be sure to change it to Live mode when your Action Flow has been published

Add additional security controls​

We recommend adding additional security controls whenever possible, to help ensure incoming requests are only received from expected sources and that payloads can be trusted.

Whitelist IP addresses​

Adding a list of allowed IP addresses will mean Atomic rejects requests not originating from those IPs. If the list is empty, requests from any IP will be allowed.

Verify signed requests​

To verify that incoming requests come from the expected source, Atomic supports verification via a signature header. This header should contain an HMAC signature derived from the request body, timestamp, and a shared secret value, and is supported by many 3rd party tools, or can be implemented on your own servers as needed. If signature verification is configured, Atomic will attempt to recreate the signature from the request and the secret, and if it doesn’t match, will reject the request. This means it’s not possible to send requests to the connector without knowledge of the secret.

Signature verification is configured using a JSON object. To perform signature verification, Atomic needs to know the following values listed below. You find these values from the system that is sending the webhooks (e.g. Stripe, ServiceNow, Salesforce,...), and enter them in the Authentication field.

  • shared secret: The secret value shared between the webhook source and Atomic, used to generate the signature.
  • algorithm & digest: sha1 or sha256, and base64 or hex respectively - these determine the hashing method used to generate the signature.
  • signature and timestamp location: For each of these, specify the request header where they’ll be provided. Optionally, if both values or multiple signatures are provided in one header, specify a parsePrefix. For example, given the header value x-signature: v1={signature}, t={timestamp} , both signature and timestamp are provided in the x-signature header, and should have parsePrefix values v1= and t= respectively.
  • template: a template string defining how the hashing algorithm’s text input should be constructed, containing [timestamp] and [payload] tokens. [timestamp] will be replaced by the raw timestamp from the header, and [payload] by the raw request body
Example​

The following configuration verifies a Stripe webhook request:

{
  "algorithm":"sha256",
  "digest":"hex",
  "data":{
    "signature":{
        "header":"stripe-signature",
        "parsePrefix":"v1="
    },
    "timestamp":{
        "header":"stripe-signature",
        "parsePrefix":"t="
    }
  },
  "template":"[timestamp].[payload]"
}

Activate your Webhook trigger to generate live event and cards​

When you first create a Webhook trigger, it is created in a Test mode, which means any requests received at the URL for the Webhook trigger will generate Test cards and analytics, not Live cards and analytics.

After you have tested the configuration, you need to activate it to change its status to Live, so that incoming webhook requests can generate Live cards. This is a precaution that protects you against inadvertently generating Live cards before you’re ready.

To change a Webhook trigger from Test to Live, select the trigger from the Action Flow canvas then change the mode using the drop-down selector in the properties trigger properties menu on the right.

Editing a live Webhook trigger​

Before you make changes to a live Webhook trigger, we strongly recommend that you switch it from Live to Test mode. This ensure any changes you make and save, don’t potentially cause unexpected Live cards to be sent.

To switch a live Webhook trigger to test mode, select the trigger from the Action Flow canvas then change the mode using the drop-down selector in the properties trigger properties menu on the right.

Disable a Webhook trigger​

To disable a Webhook trigger, select the trigger from the Action Flow canvas then change the mode using the drop-down selector in the properties trigger properties menu on the right.

Segment triggers​

Atomic is constantly evaluating whether your customers need to enter or exit segments, based on the filter rules for each segment. When a customer enters, or exits a segment, the Atomic platform emits events and these events can be used to dynamically trigger your Action Flow for that customer.

Dynamic segments, which are explained in the segments article, are a powerful and versatile way to trigger your Action Flow, especially when you don't need to, or can't send trigger events via API or Webhook.

tip

If you're new to how segments work in Atomic, we'd recommend checking out the the segments article as well as checking out the customer data model article which explains the different types of customer data Atomic can use to help you build segments.

Basic segment trigger example​

Let's imagine you want your customers to receive an Atomic card the next time they're seen using your iOS app.

You would start by creating a Segment from the Customers dashboard, which might include a filter that for any customers last seen on iOS after the start date of your outreach campaign. This type of filter is likely to match your target customers, and they are only like to enter the segment once. You might name that Segment 'iOS users seen after 1 March 2024'

Next, you would add a Segment trigger to your Action Flow, and set it to trigger when customers enter the iOS users seen after 1 March 2024 segment. After your Action Flow is published, any users who then enter that Segment will be triggered into the Action Flow.

When you're finished with the outreach, you can archive the Action Flow, and delete the Segment as it's no longer needed.

When to consider a segment trigger​

Segment triggers are most commonly used in situations where:

  • You have the necessary customer data (or metadata) in Atomic to support building dynamic segment
  • You want to sync customer data, and custom events into Atomic, and have Atomic do as much of the orchestration as possible
  • You don't have a way to send API, or Webhook requests
Make sure you segment is designed to behave as you expect

Because Segment triggers will run every time a customer enters, or exists your selected segment (whichever option you chose), it is critical to be sure that your Segment is designed correctly. If you don't want the same customer to be sent the same action flow multiple times, you need to make sure your Segment is designed in such a way that customers won't, or can't exist and re-enter. Be sure to checking out the the segments article. If you get stuck or need a hand, reach out to us for support.

What if my customers are already in a segment?​

Segment triggers use the events emitted when customers enter, or exit your segments. So if you have an existing segment and some customers were already in that Segment before you publish your action flow, the Action Flow will not automatically trigger for those users. However, during the publish step, Atomic will count how many customers are already in the segment at that point, and give you the option to have the Action flow manually triggered for those customers when the action flow is published. This gives you a simple way to trigger the Action Flow for existing segment members.

What happens if I edit my segment while it is being used as a segment trigger?​

When you change your Segment, Atomic will re-evaluate the segment. Customers who no longer match the filter will exit the segment, existing segment members who also match the edited filters will remain in the segment, and customers who didn't previously—but now do—match the filters, will enter the segment. For those who exit, a Segment Exited event will be emitted, which may trigger an Action Flow (if you're watching for exited events), and those who join will emit Segment Entered events. Those remaining in the segment will not have the Action Flow triggered a second time.

Salesforce Marketing Cloud Journey Builder Triggers​

Atomic offers a Salesforce Marketing Cloud Journey Builder integration which enables you to trigger action flows directly from within Salesforce Marketing Cloud Journeys. Once the integration is enabled in Atomic environment, you'll see an option when adding triggers, allowing you to select Salesforce Marketing Cloud Journey Builder as a trigger type.

Check out the Salesforce Marketing Cloud Journey Builder article for details on how to set up the integration, and how to use it in your Action Flows.

Adobe Marketo Self-Service Flow Step Triggers​

Atomic offers an Adobe Marketo integration which enables you to trigger action flows directly from within Marketo campaigns using Self Service Flow Steps. Once the integration is enabled in Atomic environment, you'll see an option when adding triggers, allowing you to select Adobe Marketo Self Service as a trigger type.

Check out the Adobe Marketo Engage Self Service Flow Step article for details on how to set up the integration, and how to use it in your Action Flows.

Event triggers​

Event triggers give you the ability to respond to a single analytic or custom event seen by the Atomic platform by triggering an Action Flow for the relevant customer. This is convenient for scenarios where you don't need, or want to create and manage a dynamic segment.

By default event triggers retrieve the user to target for the flow from the endUserId property in the event payload, and variables from properties. You can edit where the trigger gets these properties from, and add other properties, by choosing your event trigger and clicking "Edit event mapping". An event mapping must output a payload in a particular shape - aty the very least a targetUserIds property must be set to a string.

Since it is possible to create Event triggers from almost any event, they have a safety mechanism to avoid infinite recursion. For example, an event trigger on the action-flow-started event would start an Action Flow, that Action Flow would emit that same event type which would then start another Action Flow - and so on. Due to this, events from an Action Flow are stopped from triggering the event trigger for that same Action Flow.

Manually triggering Action Flows​

Atomic supports the following ways to manually trigger Action Flows:

Upload a CSV file via the Workbench​

Using the Action Flow bulk send tool you are able to upload a CSV file which Atomic will then use to trigger a batch of Action Flows.

API bulk-start CSV upload​

Similar to the Workbench method, you can also use the Atomic API to bulk-start an Action Flow by providing a CSV batch file. The steps to do this are covered in the Action Flow API documentation

Manually trigger an Action Flow via the Workbench Customers dashboard​

A common pattern for an Action Flow that will only be sent once, or perhaps a few times, is to manually trigger for the target customers from within the Workbench. When there's no need to have a dynamic trigger it is quick and simple to manually trigger your flow.

Pre-requisites​​

To manually trigger an Action Flow from the Workbench, you'll need to be aware of the following:

  • You can only trigger your Action Flow for customers that have a profile in Atomic. The profile can be as minimal as the auto-generated profile we create when we first see them in your app, or a profile enriched with customer data you've synced, but in any case, you can't use the Customers dashboard to manually trigger an Action Flow for completely new customer.
  • You can only trigger published Action Flows. Because the trigger events will be live events (not test events) you will only be able to select from a list of published Action Flows. If you haven't yet published your Action Flow, do this first.
  • There is a limit to how many customers you can target in a single manual action. The Workbench will let you know if you're exceeding the limit when you select your target customers.

Manually triggering your Action Flow​

  • From the Customers dashboard, either click into an existing saved Segment, or add filters to find the set of customers for whom you want to trigger your Action Flow
  • When you've filtered to the right set of customers, click the 'Send to N customers' button in the top-right of the screen
  • From the options you're presented, select your Action Flow
  • Don't fill in any of the basic details inputs, these are used when sending legacy cards (the equivalent settings should already be be configured within your Action Flows on the Send a card steps)
  • Click Send. At this point, Atomic will begin the process of manually triggering your Action Flow for each of your selected customers. If you've selected a large group, this can take some time to fully process, which will happen in the background.

Only need to send to a specific customer?

Find the customer record by applying a filter, click the checkbox next to the Customers details, then select 'Send card to 1 customer' and follow the steps above.

Last updated on