Airship — Send Custom Event

Airship is a customer engagement platform that helps marketers connect with their customers across every stage of the customer lifecycle.

Send one Airship custom event for a customer as soon as a real-time journey reaches an Activate node, using the custom events endpoint. Amperity sends one event for each send, so that an Airship automation, sequence, or scene that is triggered by the event name can act on it, subject to its own conditions.

This connector sends a custom event and nothing else. It does not write Airship attributes; send the data that the triggered message needs as event properties instead. To send custom events from a scheduled query rather than in real time, use the Airship Custom Events destination.

This connector sends from a real-time journey. See Real-time destinations.

Beta

The Airship — Send Custom Event connector is in beta. Contact your Amperity representative to learn more.

Requirements

  1. An Airship OAuth client for the project that receives the events, granted the Events (evt) scope. Amperity requests only that scope. A client set up for the Airship Custom Events destination already has it. See OAuth and API security in the Airship documentation.

  2. An Airship automation, sequence, or scene that is triggered by the custom event name that you enter on the Activate node. Amperity sends the event; it does not create the trigger, and it does not check that anything in Airship is triggered by the name.

Credentials

This connector uses the “airship-custom-events” credential type, the same one that the Airship Custom Events destination uses, so a credential set up for that destination can be selected here. The credential has a Client ID, a Client Secret, an App Key, and a Data Center.

An “airship-attributes” credential, set up for the Airship Attributes destination, cannot be selected for this destination, even when its OAuth client is granted the Events scope. To use the same OAuth client, create an “airship-custom-events” credential with its Client ID and Client Secret.

Name and description

The name and description for a credential.

Client ID

The client ID from a set of OAuth client credentials that you create in your Airship project. It is the identifier half of the credential pair.

Client Secret

The client secret paired with the Client ID. Airship shows the client secret only once, when you create the credentials, so record it before you leave the page.

App Key

The app key for the Airship project that receives the events. It scopes the credential to a single project and identifies the integration to Airship support.

Data Center

The Airship data center that hosts your project. Select the region that matches your project:

  • US

  • EU

Credentials are regional: a project’s credentials sent to the other data center fail as though they were invalid. Confirm the region with your Airship project settings. Defaults to US.

Amperity requests an OAuth token from the Airship token endpoint for the selected data center, sending the Client ID and Client Secret with HTTP Basic authentication. The token is for the project named by the App Key, with the Events (evt) scope. Amperity then sends each event to POST /api/custom-events on the API host for the same data center:

  • US: tokens from https://oauth2.asnapius.com, events to https://api.asnapius.com.

  • EU: tokens from https://oauth2.asnapieu.com, events to https://api.asnapieu.com.

When you save the destination, Amperity tests the connection by sending the custom events endpoint a request that holds an empty list of events. The request contains no event, so the test messages no one. When Airship answers with 401 or 403, the test reports a credential error and asks you to check the Client ID, Client Secret, and App Key, the Events scope, and the Data Center. Any other failure, including no answer, is reported as a failure to reach Airship and asks you to check that Data Center matches the region that hosts the project.

Settings

Name and description

The name and description for a destination.

Business user access

By default a destination is available to all users who have permission to view personally identifiable information (PII).

Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.

Enable the PII setting checkbox to allow limited access to PII for this destination.

Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.

This connector has no other destination settings. Everything else is configured on the Activate node.

Activate node settings

The rest of the configuration for this connector belongs to the journey that sends to it. Add this destination to an Activate node, then configure the following fields on the node’s Payload tab. Two nodes may send to the same destination with different event names, identifiers, interaction values, and custom attribute values. Attributes mapped in Event properties are set once for the destination in the journey, so every node that sends to it sends the same mapped attributes.

Custom event name

Required. The event name that your Airship automation, sequence, or scene is triggered by. Amperity has no list of event names to choose from, so enter the exact name. Amperity converts the name to lower case before sending it and changes nothing else: “Cart Reminder” is sent as “cart reminder”. Set the Airship trigger to the lower-case name. Amperity does not send an event whose name is longer than 255 characters.

Airship identifier

The kind of Airship identifier that Identifier attribute holds. Amperity sends the value under this key in the event’s “user” object. Select one of:

  • named_user_id, an Airship named user ID. Amperity does not send a named user ID longer than 128 characters.

  • channel, amazon_channel, android_channel, ios_channel, or web_channel, an Airship channel ID. Amperity does not send a channel ID that is not in UUID format.

There is no option for email_channel, sms_channel, or open_channel, so an event cannot be sent to an email or SMS channel directly. A named user ID can itself be an email address, when that is how the Airship project assigns named users. Defaults to named_user_id, which Amperity also uses when a node has no value for this field.

Identifier attribute

Required. The Amperity attribute that holds the customer’s identifier of the kind selected above. Amperity sends a text value unchanged, and a whole number as text; it does not trim, normalize, or look up the value. See custom events for the identifiers Airship accepts. When Airship rejects an identifier, that send fails without another attempt, as described under Failed sends. A customer with no value for the attribute is not sent: there is no fallback to the Amperity ID.

Interaction ID

Optional. A fixed value that Amperity sends as the event’s “interaction_id”. A blank value is not sent. Amperity sends the value unchanged, and does not send an event whose interaction ID is longer than 255 characters. See custom events for how Airship uses it.

Interaction type

Optional. A fixed value that Amperity sends as the event’s “interaction_type”, such as “PUSH” or “SMS”. A blank value is not sent. Amperity sends the value unchanged, and does not send an event whose interaction type is longer than 255 characters.

Event properties

Optional. The properties sent with this event, for personalizing the triggered message and for branching in the Airship automation. Select Edit to map Amperity attributes to property names on the Attributes tab, or to add fixed values on the Custom attributes tab. The node itself has no Attributes tab for this connector: Event properties is where attributes are mapped. Amperity sends them in the event’s “properties” object, using each property name exactly as entered, including case. When there are no event properties, the event has no “properties” object.

Amperity sends each value with its type, and does not check or convert it: text, numbers, true or false values, nested values, and lists are sent as they are. Date values are sent as “YYYY-MM-DD” text. An attribute that the customer’s profile has with no value (null) is sent as null. An attribute that the profile does not have, or an enriched or custom attribute with no value, is left out of the event. See custom events for the property values Airship accepts. When Airship rejects a property value, that send fails without another attempt, as described under Failed sends.

A property named “occurred”, “event_name”, “interaction_id”, or “interaction_type” is sent as an ordinary property. It does not change the event’s time, name, or interaction values.

Amperity does not send an event whose properties are larger than 65,536 bytes, measured once they are encoded as JSON.

Request body

Amperity sends each event as a list that holds one event. The event’s “occurred” time is the time Amperity queued the send, in UTC to the second and without an offset. Every attempt for the same send carries the same time.

For example, with Custom event name set to “Cart Reminder”, Airship identifier set to named_user_id, Interaction type set to “PUSH”, and event properties named “first_name” and “cart_total”, Amperity sends:

[
  {
    "occurred": "2026-10-28T17:04:12",
    "user": {
      "named_user_id": "customer-123"
    },
    "body": {
      "name": "cart reminder",
      "interaction_type": "PUSH",
      "properties": {
        "first_name": "Ada",
        "cart_total": 42.5
      }
    }
  }
]

Checked before sending

Before it sends an event, Amperity checks it against the following rules, and no others. When a check fails, Amperity does not send the event, and the send fails without another attempt. For every check except the last, the failure message names the node field or the attribute to fix. Amperity reports the first of these that applies:

  • The custom event name is blank, or is longer than 255 characters.

  • The interaction ID or the interaction type is longer than 255 characters.

  • The customer has no value for the identifier attribute.

  • The identifier is neither text nor a whole number, such as a decimal number or a list.

  • A named user ID is longer than 128 characters.

  • A channel ID is not in UUID format.

  • The event properties are larger than 65,536 bytes.

  • The send was queued more than 89 days earlier. Only a send that waited in the queue can fail this check, because Amperity normally sends an event moments after the journey queues it.

The first two are problems with the node’s settings, and fail every send from that node until they are fixed. The others are problems with one customer’s data, and fail only that customer’s send.

An event that passes these checks can still be rejected by Airship, as described under Failed sends.

Failed sends

Amperity makes up to three attempts at each send. Each new attempt is scheduled between 200 and 700 milliseconds after the previous one fails, with no backoff, so all three attempts are made within a few seconds. A rate limit or an Airship outage that lasts longer than that fails the send. Amperity does not retry a request within an attempt, so one send makes at most three requests to Airship.

How Amperity handles each failure:

  • 401 or 403. The send fails without another attempt. Check the Client ID, Client Secret, and App Key, and that the OAuth client is granted the Events scope. A credential that passed the connection test and is refused at send time may have expired or been revoked in Airship, so confirm that it is still active. A credential that Airship refuses fails every send until it is fixed. Amperity reuses its connection to Airship for each credential for up to 20 minutes, so after you edit the credential, sends can keep using the old values for up to 20 minutes. Choosing a different credential for the destination takes effect at once.

  • 400. The send fails without another attempt.

  • 429 or a server error (500 or higher). Amperity makes another attempt, up to three in all.

  • Any other status, such as 404 or 408. The send fails without another attempt. Check that the credential is for the right Airship project, and that Data Center is set to the region that hosts it.

  • No answer, such as a timeout or a dropped connection. Amperity makes another attempt, up to three in all.

When Airship answers a failed request with a reason, the failure message includes it.

A failed send and its failure message appear in two places:

  • The Recent failures table on the Profile sends tab of the Destinations page. The tab is available when real-time profiles are enabled for your tenant.

  • The Activations tab of the customer’s profile, which also shows the send’s Attempt count, such as “3 / max 3”.

Amperity keeps only the failure message from the last attempt. A failed send cannot be retried from Amperity.

Amperity sends no deduplication key with an Airship event. Every attempt is a new, identical request, so when Airship accepted an event but its answer did not reach Amperity, the next attempt sends the event again.

Amperity reports the send as successful when Airship answers with any status below 400. Amperity does not check whether the identifier matches an Airship user, or whether an automation, sequence, or scene was triggered.

Amperity limits how quickly it sends requests to Airship with each credential.