---
title: "Tracking Events - Serpwise Documentation"
description: "Define conversions, configure extraction, route events to integrations, and monitor delivery."
url: "https://serpwise.ai/docs/tracking-events/"
source: "https://serpwise.ai/docs/tracking-events/"
---
[Back to Serpwise](/)

Serpwise Documentation

Connect · Configure · Execute

Search documentation

`/`

No documentation found.

↑↓ Navigate Enter to open

Browse documentation

Tracking events are the conversion signals Serpwise captures and forwards from the gateway. They can come from first-class conversion definitions, legacy rule actions, server-to-server ingest, or the first-party AI attribution pixel.

For new setup, use **Tracking > Conversions**.

## Create a Conversion

1. Open a domain in the dashboard.
2. Go to **Tracking > Conversions**.
3. Click **New conversion**.
4. Choose **Event** for a live request-path conversion, or **Funnel** for a session-stream report.
5. Add the conversion name and platform event name.
6. Configure trigger conditions.
7. Configure extraction for value, currency, order ID, content IDs, and identity fields.
8. Select one or more destination integrations.
9. Save and keep the conversion enabled.

Event-style conversions are loaded by the gateway and evaluated on matching requests. Funnel definitions are analyzed from request-log session streams and do not fire outbound platform events.

## Trigger Conditions

Conversion definitions reuse the rules engine condition shape. Common triggers:

| Goal         | Example condition                           |
|--------------|---------------------------------------------|
| Purchase     | `url.path` equals `/checkout/thank-you`     |
| Lead         | `url.path` starts with `/contact/thank-you` |
| Add to cart  | `url.path` contains `/cart/add`             |
| Registration | `url.path` equals `/signup/complete`        |
| Product view | `url.path` starts with `/products/`         |

Conditions run against the request context. The gateway evaluates conversion definitions from the request logging path so conversion firing is independent from HTML cache hits.

## Event Names

Use event names that map cleanly to destination platforms.

| Event name             | Typical use                       |
|------------------------|-----------------------------------|
| `Purchase`             | Completed transaction             |
| `Lead`                 | Lead form submission              |
| `AddToCart`            | Item added to cart                |
| `ViewContent`          | Product or content view           |
| `CompleteRegistration` | Signup completed                  |
| `InitiateCheckout`     | Checkout started                  |
| `Subscribe`            | Newsletter or subscription signup |

Targets can override the event name per integration. For example, one conversion can send `Purchase` to Meta, `purchase` to GA4, and `order_completed` to a webhook.

## Extraction

Extraction tells the gateway how to build the payload.

| Field          | Description                           | Example                                                            |
|----------------|---------------------------------------|--------------------------------------------------------------------|
| `value`        | Monetary value.                       | CSS selector, regex, request body field, or JSON-LD product price. |
| `currency`     | ISO currency code.                    | `USD`, `.currency-code`, or a static default.                      |
| `order_id`     | Transaction ID for exact dedupe.      | `.order-number` or `order_id=(\w+)`.                               |
| `content_name` | Product or content name.              | `.product-title`.                                                  |
| `content_ids`  | Product IDs or SKUs.                  | `.product-sku`.                                                    |
| User data      | Email, phone, browser, and click IDs. | Cookies, request data, or form payload.                            |

## Targets and Routing

Each conversion has one or more targets:

| Target option       | What it controls                          |
|---------------------|-------------------------------------------|
| Integration ID      | Which destination receives the event.     |
| Event name override | Optional destination-specific event name. |

Per-integration transformation rules can further rename, drop, set fields, or route events before delivery. Configure those rules by editing an integration in **Tracking > Integrations**.

## Counting and Deduplication

Conversion definitions support counting controls:

| Mode               | Behavior                                                                 |
|--------------------|--------------------------------------------------------------------------|
| `every`            | Count every matching request.                                            |
| `once_per_visitor` | Collapse repeats from the same visitor/session within the dedupe window. |

If an order ID is extracted, it acts as an exact conversion key so the same order is not counted repeatedly.

The forwarding pipeline also deduplicates with:

- in-memory gateway dedupe,
- database uniqueness on domain, dedupe key, and platform,
- platform event IDs.

## Legacy Rule Action

The rules engine still supports `fire_conversion_event`. Use this when you need a conversion event embedded inside a broader rule workflow.

For most setups, prefer **Tracking > Conversions** because conversion definitions are easier to list, edit, toggle, report on, and explain to non-technical operators.

## Server-to-Server Ingest

Backend systems can send events to:

```
POST /tracking/ingest
```

The gateway requires `X-Internal-Key`, a `domainId`, and 1-100 events. Each event uses `platform`, `eventName`, optional value/currency, user data, and custom data.

See [Tracking Ingest API](/docs/tracking-api).

## Event Log

Use **Tracking > Event Log** to inspect persisted rows.

Each row can include:

- timestamp,
- event type,
- source URL,
- platform,
- status,
- extracted value and currency,
- order ID,
- platform response,
- error message,
- attempt count,
- replay count,
- payload revision history.

You can filter by platform, status, event type, or integration, export CSV, open a detail sheet, edit a payload revision, and replay failed events.

## Live Debugger

Use **Tracking > Live Debugger** during setup. It streams events over Server-Sent Events as the gateway processes them.

Statuses:

| Status             | Meaning                                             |
|--------------------|-----------------------------------------------------|
| `forwarded`        | Platform accepted the event.                        |
| `failed`           | Credential, timeout, validation, or platform error. |
| `deduplicated`     | Event was recognized as a duplicate and not sent.   |
| `consent_denied`   | Required consent category was missing.              |
| `transformed_drop` | A transform rule dropped the event.                 |

See [Live Event Debugger](/docs/tracking-debugger).

## Analytics

Use **Tracking > Conversions > Analytics** for reporting:

- total conversions,
- success rate,
- tracked revenue,
- platform comparison,
- conversions over time,
- revenue over time,
- event-type distribution,
- top converting pages,
- conversion rate by page,
- page views by page type,
- integration health.

## Troubleshooting

| Symptom                      | Check                                                                                             |
|------------------------------|---------------------------------------------------------------------------------------------------|
| No events appear             | Confirm the conversion is enabled, conditions match the URL, and the gateway cache has refreshed. |
| Events are `failed`          | Open the event detail, read the platform response, and test the integration credentials.          |
| Events are `consent_denied`  | Confirm CMP cookies include the categories required by the target integration.                    |
| Events are `deduplicated`    | Check order ID, session, counting mode, and dedupe window.                                        |
| Value or currency is missing | Review extraction, structured data, Open Graph product data, and transform rules.                 |

## Next Steps

[**Tracking Overview**  
→  
\
Understand the full tracking pipeline.](/docs/conversion-tracking)

[**Tracking Integrations**  
→  
\
Connect and test destination credentials.](/docs/tracking-integrations)

[**Live Event Debugger**  
→  
\
Watch events as they are processed.](/docs/tracking-debugger)