Skip to main content

Connector triggers

Connector triggers enable incoming webhook requests to trigger Action Flows.

When to use a Connector trigger​

Connector triggers are most commonly used in situations where:

  • the triggering event occurs in a system that can’t make OAuth2 requests to the Atomic API, or
  • you don’t have control over the shape of the request payload body being sent to Atomic from the initiating system

These situations are common when sending real-time requests to Atomic from another cloud system, such as a Marketing Automation or CRM platform.

How Connector triggers work​

Each Connector trigger provides a URL unique to a specific Action Flow that you send webhook requests to. When requests are received, Atomic attempts to trigger an Action Flow.

Create a Connector trigger​

Connector triggers are a very flexible feature, designed to support many different integration scenarios. Because of this, you get to decide how Atomic should handle many aspects of the the incoming webhook request. Follow these steps to create and configure a new Connector trigger:

1. Add a Connector trigger​

From the Triggers tab within a card, choose ‘Add connector’ in the 'Connector triggers' section.

2. Add a sample payload​

The first step in configuring a Connector trigger is to provide a sample payload. This important step tells Atomic what shape to expect incoming data to be in.

To add a sample, you can simply paste an example into the Sample connector payload field, but we recommend you:

  1. Choose the Get new sample option.
  2. Copy the unique URL for this Connector trigger.
  3. Make a POST or PUT request to the URL, with a sample payload within the JSON body of the request. This sample payload request does not need to be authenticated.
  4. Wait for Atomic to pick up the incoming request and populate it into the Sample connector payload field.

3. Map the incoming payload​

Before attempting to process an incoming webhook received at a Connector trigger URL, Atomic expects the shape of the request body to conform to the following schema:

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

  // all other properties are optional
  cardOptions: {
    priority: 5,
    expires: "2030-01-04T00:10:00.584Z",
    // use either `expires` OR `expiresInterval` (not both)
    expiresInterval: "PT1H",
    embargo: "2030-01-04T00:10:07.584Z",
    targetStreamIds: ["PAxrYyaO"]
  },
  // idempotency key
  flowInvocationId: "6fad5d419180",
  // key/value pairs of variables used within the Action Flow
  variables: {
    variable_name: "variable value",
    another_variable_name: "..."
  },
  notificationDetail: {},
  metadata: {}
}

However, since you may not have control of the the shape of the data from the source system, Connector triggers expect you to define a mapping, which Atomic will apply to incoming webhook requests before attempting to process them. After mapping, your payload must conform to the above schema.

Atomic supports two types of mapping:

Structured mapping​

This is the mapping option you will see when you first set up your Connector trigger, in the ‘Mapping’ tab. After pasting in a sample payload, or fetching a live sample, you can use the structured mapping tool to map data from your sample incoming request, to the expected schema above. You can directly reference properties from your sample payload using JSONPath dot notation, or pick mapped values from the select drop-downs.

Script mapping​

You can also write a mapping script using JavaScript. Switch to the ‘Script’ tab within the mapping area, then from the Choose Preset option, select Default to load a basic script mapping you can then modify to suit your needs.

Mappable properties​

In the bottom-right of the setup screen, you can see a list of properties Atomic has found within your sample payload. Any property display in this list, is available to be mapped.

4. Validate your mapping​

The top-right side of the setup screen is a preview of your mapped sample request. This preview will display errors if your mapping is failing, and helps you ensure that the values in your mapping are correctly placed within the mapping output.

Test the Connector trigger​

There are two ways to test your Connector trigger:

Send a test card from the setup screen​

Once you save a Connector trigger, you will be able to send a test card from its setup screen. Atomic will use the sample payload and the saved mapping.

Send a test card by sending a webhook request to the Connector trigger URL​

You can also send a webhook to your new Connector 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.

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. You can do this by selecting Security settings from the overflow menu next to the connector trigger.

Connector trigger security settings

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, request 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 Edit security dialogue window.

  • 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 Connector trigger to generate live cards​

When you first create a Connector trigger, it is created with a Test status, which means any requests received at the URL for the Connector trigger will generate Test cards, not Live cards.

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 Connector trigger from Test to Live, on the Triggers tab, choose Activate from the overflow menu on the right-ride.

Understanding auto-pause​

If Atomic receives an incoming webhook request where the body of the request is not shaped like the sample used to configure the Connector trigger, the Connector trigger will be automatically paused. This is a safeguard to ensure unexpected requests, or unexpected data shapes do not send unexpected cards.

In the Triggers tab for a card, you can see whether a Connector trigger has been paused, and reactivate it after you have reviewed its configuration.

Editing a live Connector trigger​

Before you make changes to a live Connector 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 Connector trigger to test mode, from the Triggers tab, choose Switch to test mode from the overflow menu on the right-ride.

Disable or delete a Connector trigger​

To disable a Connector trigger, from the Triggers tab, choose Disable from the overflow menu on the right-ride. To delete a Connector trigger, first disable it, then from the menu choose Delete.

Last updated on