Ometria

Datafly Signal delivers events to Ometria server-to-server using the Data API push endpoint. Events are pushed as Ometria custom events, linked to a contact by email, and become available for segmentation, journeys, and cross-channel campaigns (email, SMS, push) — without any client-side Ometria tag.

Prerequisites

Before configuring Ometria in Signal, you need an Ometria account with a Data API key, and the custom event types you intend to send must be set up in Ometria.

Step 1: Generate a Data API key

In Ometria, go to Settings > API keys.
Create a key with push / write access to the Data API.
Copy the key — it is sent in the X-Ometria-Auth header on every request.

⚠️

This is the Data API key, not the Website Personalisation (Query API) key. The Query API uses Basic authentication on a different host and will not work with this integration.

Step 2: Set up your custom events in Ometria

Ometria accepts a custom event push immediately, but it will not act on an unknown event type until that type is configured.

Go to Settings > Custom events.
Create each event type you plan to send (for example product_viewed, cart_add, order_completed).
Define the properties you want available in templates and segments.

Event type names should be kept under 512 characters — longer values are truncated by Ometria.

Configure in Signal

Configuration Fields

Field	Required	Description
`api_key`	Yes	Your Ometria Data API key with push access. Found in Settings > API keys. Sent in the `X-Ometria-Auth` header.

Management UI Setup

Add the integration

Go to Integrations > Add Integration > Ometria.

Choose a preset

Select the Retail preset for the standard e-commerce funnel (product views, cart, checkout, purchase), or start from Default.

Enter your API key

Paste your Ometria Data API key into the api_key field.

Choose the consent category that governs this integration (typically marketing).

Save

Click Save. Signal begins delivering matching events to Ometria.

API Endpoint

POST https://api.ometria.com/v2/push
X-Ometria-Auth: {api_key}
Content-Type: application/json

The request body is a JSON array of records (up to 100 per request). A single request contains only one record type — Signal sends custom_event records. A successful push returns 202 Accepted.

Identity Signals

Ometria links each custom event to a contact using the contact’s email address.

Signal	Ometria field	Description
Email	`identity_email`	The contact’s email address, sent in plain text (Ometria keys contacts on email). Provided by `datafly.identify()`.

Ometria matches on the raw email address, so identity_email is not hashed. Email is the link between an event and a customer profile — events without it are still accepted but cannot be attributed to a contact.

To attach identity, call datafly.identify() when the user logs in, registers, or submits their email:

datafly.identify("user-123", {
  email: "jane.doe@example.com"
});

Event Mapping

Retail preset

Signal event	Ometria `event_type`
`page`	`page_view`
`Products Searched`	`search`
`Product Viewed`	`product_viewed`
`Product Added to Wishlist`	`wishlist_add`
`Product Added`	`cart_add`
`Product Removed`	`cart_remove`
`Checkout Started`	`checkout_started`
`Order Completed`	`order_completed`

All other events are dropped. To customise, edit the integration’s Field Mappings in the Management UI.

Example: Product Viewed

Datafly.js call:

datafly.identify("user-123", { email: "jane.doe@example.com" });
 
datafly.track("Product Viewed", {
  product_id: "SKU-A",
  product_name: "Merino Crew Jumper",
  variant: "navy-m",
  price: 79.00,
  currency: "GBP",
  category: "Knitwear"
});

Ometria push payload sent by Signal:

[
  {
    "@type": "custom_event",
    "id": "evt_abc123def456",
    "timestamp": "2026-06-06T15:32:52+00:00",
    "event_type": "product_viewed",
    "identity_email": "jane.doe@example.com",
    "properties": {
      "product_id": "SKU-A",
      "product_name": "Merino Crew Jumper",
      "variant_id": "navy-m",
      "product_price": 79.00,
      "currency": "GBP",
      "category": "Knitwear",
      "page_url": "https://example.com/products/merino-crew"
    }
  }
]

Testing Your Integration

Trigger a test event

Identify a contact and fire a tracked event on your site (for example, view a product).

Check Signal’s event debugger

In the Management UI, open the Event Debugger for the integration and confirm the event was delivered with a 202 response.

Verify in Ometria

In Ometria, open the contact’s profile and confirm the custom event appears in their activity, or check the custom-event listing for the event type.

Troubleshooting

Problem	Solution
`403 Forbidden` on every push	The API key is missing, invalid, or is a Query API (Website Personalisation) key rather than a Data API push key. Generate a Data API key under Settings > API keys.
Push returns `202` but the event never appears against the contact	The `event_type` is not configured in Ometria. Create it under Settings > Custom events.
Event delivered but not linked to a customer	`identity_email` is missing. Call `datafly.identify()` with the contact’s email before tracking.
`400 Bad Request`	The batch mixed record types or exceeded 100 records, or the body was malformed. Signal sends only `custom_event` records in batches of up to 100, so check for a custom Field Mapping change.
Event type appears truncated	Event type names over 512 characters are truncated by Ometria. Use a shorter `event_type`.

Rate Limits & Batching

Limit	Value
Records per push request	100 (Signal batches automatically)
Record types per request	1 (Signal sends only custom events)

Signal batches events automatically, sending up to 100 custom events per push request. The default settings are sufficient for most deployments.

Sendlane Ortto