How to capture and send server-side events

Server-side event collection captures customer signals from backend systems and sends them to the platform through APIs.

Use server-side collection when you need higher reliability, clearer governance, or business events that the browser can't capture. These events include:

• Events defined by backend truth (such as payment success or subscription canceled)

• Events that depend on identifiers unique to business systems

• Events that require stronger control over data sharing and consent enforcement

• Events that are time-sensitive and need to be captured even if the user isn’t currently on the website (such as a contract end date approaching)

When to use server-side events

Server-side collection is the better fit than web event collection when:

• The event is defined by backend truth (for example, payment success, subscription canceled).

• You need stronger control over data sharing and stronger enforcement of consent.

• The use case depends on identifiers that are unique to business systems.

• You want less exposure to browser blockers and script failures.

• Web teams limit third-party scripts for performance or governance reasons.

Example: churn prevention from subscription data

An example use case is when a subscription business wants to target users whose contract end date is approaching. Using the backend data, this works even if the user does not visit the website during the critical window:

1. The billing system updates the contract end date when a user signs up or renews.

2. The contract end date update is sent server-side as an event with the new end date.

3. An audience is defined as "contract ends in 30 days and renewal not confirmed".

4. A journey triggers reminders across email and paid media.

5. If the user renews, the billing system sends a renewal event that removes them from the journey.

Before you begin

Make sure that you have the following details ready before capturing and sending server-side events:

• You have API credentials for the platform (provided during onboarding).

• You have identified which backend systems will send events.

• You have agreed on event naming conventions and required properties.

• You know which customer identifier (such as email address, customer ID, phone number) will be included in each event.

Instructions

Step 1: Identify events to send

Determine which business events your backend systems should send. Prioritize events that:

• Define key outcomes (purchase, subscription start, renewal, cancellation).

• Trigger time-sensitive journeys (contract end date approaching, trial expiring).

• Update eligibility for audiences (consent changes, customer status updates).

Common server-side events:

Step 2: Structure the event payload

Each event payload should include:

• Event name: A stable, descriptive name (for example, purchase_completed).

• Timestamp: When the event occurred (ISO 8601 format recommended).

• Customer identifier: Customer ID, email hash, or another stable identifier.

• Properties: Context needed for targeting or journey logic.

Example payload:

{
  "event": "purchase_completed",
  "timestamp": "2024-01-15T14:32:00Z",
  "customer_id": "cust_12345",
  "properties": {
    "order_id": "ord_98765",
    "order_value": 149.99,
    "currency": "EUR"
  }
}

Step 3: Send events via API

Send events to the Data Activation platform's event ingestion endpoint. Use HTTPS POST requests with your API credentials.

Best practices:

• Send events as close to real-time as possible for time-sensitive use cases.

• Use retries with exponential backoff for transient failures.

• Generate a log of API responses for debugging.

• Validate payloads before sending to catch errors early.

Step 4: Handle errors

Common error scenarios:

Verify the setup works

After setting up the event capture, confirm events are arriving correctly:

1. Send a test event with a known customer identifier.

2. Check the platform to verify the event appears on the profile timeline.

   • If events aren't appearing, it's possible that the API call is failing. Check the API response codes and logs.

   • If events go to the wrong file, there is an identifier mismatch. Check that the customer ID matches the existing profile.

   • If the events are delayed, there are timestamp issues. Confirm that the timestamps are in the correct format.

   • If there are duplicate events, they're likely caused by retries without deduplication. To fix the issue, add an idempotency key or an event ID.

3. Confirm the event timestamp matches what you sent.

4. Test that audiences or journeys using this event trigger as expected.

More resources

• Data ingestion

• Profile ingestion from business systems

• Identity resolution and profile lifecycle

• Environments, testing, and rollout practices