Skip to main content

Webhooks

You can register one or more Webhook subscriptions to receive analytics events created by the Atomic platform in near real-time.

Events available in webhooks include our standard analytics events, and can also include your customers individual card response values if required.

Webhook payloads are in the shape of our analytics events, but you can change the shape of the event payload using JavaScript to map it to your required shape.

Webhook requests are signed by Atomic, and can be sent to authenticated API endpoints using webhook credentials that you save in the Workbench. Once configured, credentials can be reused between more than one webhook subscription, as well as when making API requests via Send Request steps in Action Flows.

Webhooks requests that fail are retried a number of times using an exponential back-off approach. A webhook subscription will be automatically paused after we detect failed requests that were not eventually be delivered.

Creating a webhook subscription​

From the Webhook subscriptions configuration tab you'll see all existing subscriptions, and their active status.

Workbench view of webhook subscriptions
Create and manage webhook subscriptions from the Subscriptions configuration tab

Before you start: If this webhook subscription will be sending requests to an endpoint that requires authentication, create a Webhook credential (details below) before setting up your subscription. Once created, you can reuse the credential on multiple subscriptions if needed.

  1. To create a subscription, click New subscription.
  2. Select card - (optional) choose a specific card to only get events scoped to that card, or leave this empty to receive events relating to all cards and Action Flows. Note: once saved, this setting cannot be edited.
  3. Enter webhook name - (required) give your subscription a name that will help you distinguish one from another in your list.
  4. Select event types - (required) choose the specific events you want to receive. You can edit this setting later if required.
  5. Request method - (required) if the default request method (POST) isn't what you need, you can change it to a PUT. If you need to make a different request type, consider using a Send Request step within a specific Action Flow, which supports a wider range of request types.
  6. URL - (required) enter the URL you want to send events to. Just testing? Consider using a service like webhook.site to generate a temporary URL to send events to, then use that in your webhook subscription.
  7. Headers - (optional) if you need Atomic to send headers with the request, set them here. Note, authentication will typically be handled with a saved Webhook credential (detailed below). Headers may be useful in situations where you need to hard-code a particular header to satisfy the receiving systems requirements.
  8. Credential - (optional) if the webhook requests are going to be sent to an endpoint that requires authentication, you choose one of your saved Webhook Credentials here.
  9. Max retries - (required) The maximum amount of times to retry a failed event, can be set to 0 to disable retries (default: 23).
  10. Auto-disable - (optional) choose whether or not you want the webhook to become disabled after all available retries for a given event have been exhausted (default: enabled).
Workbench view of webhook subscriptions
Click New subscription to define a new webhook subscription

Create a mapping to change the shape of your webhook payload​

Now that you've created a webhook subscription, you can optionally create a mapping that alters that shape of the event payload. Click Edit mapping on the subscription you want to modify, then write JavaScript that creates the shape you need. In the mapping editor, the left colum shows an example of the data available to your mapping script. You can reference data with dot notation. You will write the mapping in the center column, and the right column will show you feedback and an example of the payload your mapping will create. Stuck? contact support and we can help.

Workbench view of webhook subscription mapping
Create a different payload shape for your webhook using JavaScript in our mapping editor

Webhook request log​

Beta feature

The Webhook request log is currently in beta.

In the overflow menu of the webhook subscriptions list there is an option to view the subscription's "Request log". Clicking this option will open a new tab showing details of the requests triggered by this webhook subscription. Selecting one of the log entries will populate the screen with information including the target URL and the request and response data. Request and response data is redacted for requests that are not marked as being a test (triggered by the Send test button).

Webhook credentials​

Manage credentials used to authenticate outgoing webhook requests.

There are three credential types which are currently supported, AWS signed request, OAuth client credentials and basic auth.

Add webhook authentication credentials​

  1. Go to: Configuration > Webhooks > Webhook credentials. Alternatively, open the command palette and type webhook credentials.
  2. Select New credential.
  3. Add details for the new credential.
  4. Select Save.

OAuth client credentials​

Oauth credentials are cached within the platform for 45 seconds after initially being retrieved. This is to avoid overloading the Oauth endpoint with requests. Any token expiration settings should be longer than 45 seconds.

The OAuth client credentials flow supports two request schemes:

Request body​

Example of an equivalent request using curl. Credentials are URL encoded and sent in the request body.

curl --location --request POST https://login.microsoftonline.com/common/oauth2/v2.0/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_secret=MY_CLIENT-SECRET' \
    --data-urlencode 'client_id=MY_CLIENT_ID' \
    --data-urlencode 'scope=MY_SCOPE'
URL​

Example of an equivalent request using curl. Credentials are encoded using query parameters.

curl -request GET 'http://my.auth.com/oauth2/v2.0/token?grant_type=client_credentials&client_secret=MY_CLIENT-SECRET&client_id=MY_CLIENT_ID&scope=MY_SCOPE'

AWS Signed Request​

Authenticate a request with AWS IAM, this allows webhooks to interact with AWS services. We recommend creating a bot user in AWS with IAM policy access granted only as-required for use with this credential-type.

  • Access key ID: the ID of the access key associated with the AWS IAM user.
  • Secret access key: the secret access key associated with the AWS IAM user.
  • Sign query: optionally sign the request query instead of adding an Authorization header.
  • Session token: optionally provide the session token to use IAM STS temporary credentials.

Basic auth​

Adds an Authorization header containing the provided username and password encoded as per the standard pattern.

This option is less secure, consider using the alternative options where possible.

Analytics export settings​

The data available in webhooks is determined in part by settings you can control for your Environment, these include:

  • Test card events (Whether test card events are included. If they are, they will be clearly marked as tests).
  • Request payload (whether any data originally sent in event triggers should be returned back in analytics).
  • Card response data (whether the responses for forms by customers interacting with cards should be available at all analytics events). Note: it is common to enable this, but then use Webhook mapping to remove unwanted data from individual subscriptions.

Learn how to view and edit these settings in the Analytics export settings article.

Last updated on