WebEngage

Datafly Signal delivers events to WebEngage server-to-server using the WebEngage REST API. Events are tracked against known (userId) or anonymous (anonymousId) profiles and arrive as WebEngage custom events with their attributes, ready to power journeys, segments, and cross-channel campaigns — without a client-side WebEngage SDK or pixel.

Prerequisites

Before configuring WebEngage in Signal you need a WebEngage account and your REST API credentials.

Find your data centre

WebEngage hosts accounts in regional data centres. Your dashboard URL tells you which one you are on:

Global: dashboard at dashboard.webengage.com → API host api.webengage.com
India: dashboard at dashboard.in.webengage.com → API host api.in.webengage.com
Saudi Arabia (KSA): dashboard at dashboard.ksa.webengage.com → API host api.ksa.webengage.com

Using the wrong host returns authentication or not-found errors, so confirm this first.

Get your License Code and REST API Key

In the WebEngage dashboard, go to Data Platform > Integrations > REST API.
Copy your License Code (a short account identifier, e.g. va1w264d).
Copy your REST API Key. This key is created automatically for Account Admins who have the Account Management and Update Data permissions.

⚠️

The REST API key only works if it belongs to an Admin with Account Management and Update Data permissions. Keys from other admins are rejected.

Configuration

Field	Required	Description
API Host	Yes	Your data-centre host: `api.webengage.com`, `api.in.webengage.com`, or `api.ksa.webengage.com`.
License Code	Yes	Your WebEngage account license code (path parameter).
REST API Key	Yes	Bearer token sent on every request.

Configure in Signal

Add the WebEngage integration

In your Signal management UI, open Integrations, choose WebEngage, and create a new integration.

Enter your credentials

Paste your API Host, License Code, and REST API Key into the configuration fields.

Attach to a pipeline

Attach the WebEngage integration to the pipeline that carries the events you want to forward, then select the Default blueprint preset. Save and enable the pipeline.

API Endpoint

Signal delivers custom events to:

POST https://<API_HOST>/v1/accounts/<LICENSE_CODE>/events
Authorization: Bearer <REST_API_KEY>
Content-Type: application/json

A successful request returns HTTP 200 with:

{ "response": { "status": "queued" } }

Delivery is asynchronous — queued means WebEngage accepted the event for processing.

Identity Signals

Every WebEngage event must be attached to a profile. Signal resolves identity automatically:

userId — set from Signal’s user_id when the visitor is known (logged in / identified).
anonymousId — set from Signal’s anonymous_id for visitors who have not yet been identified.

At least one is always present. When a visitor later logs in, WebEngage stitches the anonymous profile to the known userId on its side, so pre-login behaviour is retained.

Profile attributes (email, phone, name, opt-in/consent flags such as emailOptIn, smsOptIn, whatsappOptIn) are managed through WebEngage’s separate user-tracking endpoint. If you want Signal to maintain these on the profile, enable a user (Identified) delivery path alongside event tracking — the events endpoint itself carries no consent field.

Event Mapping

Signal uses GA4-style event names internally and maps them to WebEngage custom events. Event properties are flattened into the WebEngage eventData attribute object.

Signal event	WebEngage event
`page`	Page Viewed
`Signed Up`	Signed Up
`Logged In`	Logged In
`Products Searched`	Searched
`Product Viewed`	Product Viewed
`Product Added`	Added to Cart
`Product Removed`	Removed from Cart
`Checkout Started`	Checkout Started
`Order Completed`	Order Completed
`Order Refunded`	Order Refunded

Example

A Datafly.js call on your site:

datafly.track('Order Completed', {
  order_id: 'ORD-1337',
  revenue: 39.80,
  currency: 'USD',
  products: [
    { product_id: 'SKU-1', product_name: 'Givenchy Pour Homme', price: 39.80, quantity: 1 }
  ]
});

is delivered to WebEngage as:

{
  "userId": "johndoe",
  "eventName": "Order Completed",
  "eventTime": "2026-06-06T18:29:00+0000",
  "eventData": {
    "orderId": "ORD-1337",
    "amount": 39.80,
    "currency": "USD",
    "products": [
      { "product_id": "SKU-1", "product_name": "Givenchy Pour Homme", "price": 39.80, "quantity": 1 }
    ]
  }
}

WebEngage limits: event names and attribute names are max 50 characters, string values max 1,000 characters, and up to 25 attributes per data type per event. Attribute names cannot start with the reserved we_ prefix.

Testing

Trigger an event from your site (e.g. complete a test order).
In Signal, open the Event Debugger for the pipeline and confirm the WebEngage delivery shows a 200 response with {"response":{"status":"queued"}}.
In the WebEngage dashboard, open the user’s profile (search by userId) and confirm the event appears under the activity timeline. Processing is asynchronous, so allow a short delay.

Troubleshooting

Symptom	Likely cause	Fix
`401` / `403` response	Wrong API host for your data centre, or the API key belongs to an admin without Account Management + Update Data permissions.	Confirm the host matches your dashboard region and use a key from a fully permissioned Admin.
`404` response	Wrong License Code or wrong data-centre host.	Re-copy the License Code from Data Platform > Integrations > REST API and confirm the host.
`400` with `userId and anonymousId cannot be empty`	Neither identity field resolved.	Ensure the pipeline collects `anonymous_id` (and `user_id` once known) before this event fires.
`400` about reserved name	An attribute name starts with `we_`.	Rename the property in the blueprint mapping.
`429` response	Account rate limit (5,000 requests/minute) exceeded.	Signal retries automatically; reduce burst or contact WebEngage to raise the limit.
Event accepted but not visible on profile	Asynchronous processing delay, or the profile was created under a different identifier.	Wait a moment, then verify the same `userId` is used by both event and user tracking.

CleverTap Cordial