Webhook (real-time)

Send customer profile attributes to an HTTP endpoint as soon as Amperity sees the customer interaction. Amperity sends one HTTP request for each customer.

Use this connector to call your own web service, or any API that accepts HTTP requests.

This connector is named Webhook in Amperity and sends from a real-time journey. See Real-time destinations. To send a query’s results to an endpoint on a schedule, use the Webhook destination.

Credentials

Name and description

The name and description for a credential.

Credential type

Choose how Amperity authenticates with your endpoint: “webhook-single-record” for an API key, or “webhook-single-record-oauth” for OAuth 2.0 client credentials. Both credential types require a webhook URL.

Webhook URL

Required. The URL of the endpoint that receives each request. The route-params field on a journey’s Activate node can add a path to this URL.

API Key

Optional, for the API key credential type. When set, Amperity sends it in an “Authorization: Bearer <API key>” header.

Token URL

Required for OAuth. The OAuth 2.0 token endpoint. Amperity gets an access token using the client credentials grant, and then sends it in an “Authorization: Bearer” header.

Client ID and Client Secret

Required for OAuth. The client ID and secret that Amperity exchanges for an access token.

Client Authentication

Optional, for OAuth. How the client ID and secret are sent to the token endpoint: “client_secret_basic” sends them in an HTTP Basic header, and “client_secret_post” sends them in the form body. Defaults to “client_secret_basic”.

Scope

Optional, for OAuth. Space-separated scopes to request.

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.

HTTP Method

The HTTP method for each request. May be “POST”, “PUT”, or “PATCH”. Defaults to “POST”.

Content Type

The value of the “Content-Type” header. May be “application/json” or “text/plain”. Defaults to “application/json”.

With “text/plain”, the request body is not JSON. Use “application/json” unless your endpoint expects plain text.

Send Record as Body

Disabled by default, so that the customer’s attributes are nested under the payload-field set on a journey’s Activate node, for example {“data”: {…}}. Enable this option to send the customer’s attributes as the whole request body. The payload-field is then ignored.

Nest Dotted Attribute Names

Disabled by default. Enable this option to turn attribute names that contain dots into nested objects in the request body. For example, attributes mapped to “offer.code” and “offer.amount” are sent as {“offer”: {“code”: …, “amount”: …}}.

Dotted names are allowed only for attributes mapped on the Attributes tab of an Activate node, and only while this option is enabled. Custom attribute names cannot contain dots.

Important

A name cannot be both a value and the start of a dotted name. For example, mapping both “offer” and “offer.code” fails the request.

Custom Headers

Optional. Extra headers sent with every request, as “Name: value” pairs separated by semicolons. For example: “X-Client-ID: AMPERITY; X-Env: dev”. Header values cannot contain semicolons. Custom headers cannot set “Authorization” or “Content-Type”; use the credential and the Content Type setting instead.

Important

Custom headers are not stored as secrets. Do not put API keys, tokens, or other credentials in this setting.

Request ID Header

Optional. A header name, such as “X-Tracking-ID”. When set, each request gets this header with a new UUID. Log it in your endpoint so that Amperity Support can match a failed request to your logs.

Note

When you save the destination, Amperity tests the connection. With OAuth, it first gets an access token, so incorrect client credentials fail the test. It then sends a request with the JSON body {“text”: “This is a simple message.”}, using this destination’s HTTP method, content type, and headers. The test passes if your endpoint returns a success status, or a 400 or 422 that rejects the test body.

Activate node settings

The rest of the configuration for this connector belongs to each journey that sends to it. Add this destination to an Activate node in a journey, then configure the following fields on that node. Activate nodes, in the same journey or different ones, may send to this destination with different payload-field and route-params values.

payload-field

The name of the field that the customer’s attributes are nested under in the request body. Defaults to “data”. Ignored when Send Record as Body is enabled.

route-params

Optional. A path appended to the webhook URL for requests from this node. Set a fixed value, or use a profile attribute to send each customer’s request to a different path. For example, with a webhook URL of “https://api.example.com/v1” and route-params set to “customers/12345”, Amperity sends requests to “https://api.example.com/v1/customers/12345”. Any query string on the webhook URL is kept.

Request body

Each request carries one customer’s attributes:

  • The attributes mapped to this destination on the Activate node that sends the request, using the names they are mapped to. These may come from the customer’s profile or from the event that triggered the journey.

  • Any custom attributes configured on the same node. A custom attribute with the same name as a mapped attribute replaces it.

  • “amperity_profile_id”, the Amperity profile ID of the customer.

  • “amperity_collection_id”, the ID of the profile collection the customer belongs to.

For example, with the default payload-field and Send Record as Body disabled:

{
  "data": {
    "email": "customer@example.com",
    "first_name": "Ada",
    "amperity_profile_id": "...",
    "amperity_collection_id": "..."
  }
}

With Send Record as Body and Nest Dotted Attribute Names enabled, and attributes mapped to “member_id” and “offer.code”:

{
  "member_id": "SXB56540",
  "offer": {
    "code": "ACART26"
  },
  "amperity_profile_id": "...",
  "amperity_collection_id": "..."
}