Manage contracts

Overview

Hightouch Contracts helps marketing and data teams plan, manage, and enforce the data they track through event collection.

Contracts have two components::

• A contract event defines the name, type, description, and validation schema for a single event (for example, Order Completed).
• A contract is a collection of contract events that can be applied to one or more event sources (for example, E-commerce Events).

Each contract event belongs to a single contract. A contract can be applied to multiple event sources.

Create a contract

To create a new contract:

1. Go to Event collection → Contracts.
2. Click New contract.
3. Complete the setup flow:

1. Name & description

Provide a contract name and optional description.

2. Select sources

Choose the event sources this contract should monitor.

Hightouch will validate events coming from these sources against the contract schema.

3. Enforcement

Configure how Hightouch handles events that don’t match the contract.

Undeclared event types

When an event type is sent that is not defined in the contract:

• Allow — Sync the event with a warning.
• Block — Prevent the event from syncing.

After saving, you can begin adding contract events.

Add a contract event

To define an event within a contract:

1. Open your contract.
2. Click Add event.
3. Configure the event in the Configuration section:
   • Type (for example, Track)
   • Name — must exactly match the event name sent in your code (including capitalization and spacing).

1. Define the event schema

When creating a contract event, the most important step is defining its validation schema.

Under Schema, define the structure of the event payload.

You can:

• Use the visual schema builder
• Toggle Edit as JSON to directly modify the schema
• Create multiple schema versions

Hightouch uses JSON Schema Draft 7. This allows for highly complex validation of event payloads, including validating field values with regular expressions.

Define event properties

Under Properties, you can:

• Add fields using Add property
• Set field types (for example, String, Number, Array)
• Mark fields as Required
• Define nested objects or array element types

These rules determine whether an event is considered valid.

Configure context validation

Events include a context object, which contains metadata such as device information, page details, or SDK-provided fields.

Under Context, you can define validation rules for context fields.

Include built-in context fields

Enable Include built-in context fields to automatically allow standard SDK fields (like device info, page data, IP address, etc.) without having to define them manually.

If you define a context field that shares a name with a built-in one, your definition takes precedence.

2. Manage schema versions

Contracts support multiple versions of the same event schema.

Versioning is useful when it is difficult to migrate your codebase to use the latest payload. For example, when an iOS app takes a while to be updated across all devices.

After creating your first event, you can create additional versions of the schema. The first version is the "default" version, which applies to events that do not specify a version in the payload. It is recommended that your events follow an incrementing pattern (for example, v1, v2, v3), although not strictly required.

In the Schema section, you can:

• Create a new version using the + button
• Switch between versions using the version dropdown (for example, v2, default)
• Edit versions independently

When invoking an event, you can specify the schema version via:

client.track('Order Completed', {
  ...
}, {
  context: {
    htevents: {
      schemaVersion: "v2"
    }
  }
});

3. Enforcement behavior for fields

Contracts define what happens when an event contains:

• Undeclared properties (fields not defined in the schema)
• Invalid fields (missing required fields or incorrect types)

Undeclared fields

For undeclared fields within an event, you can choose:

• Allow — Sync the event with a warning.
• Filter — Sync the event but remove undeclared fields.
• Block — Prevent the event from syncing.

Invalid fields

For invalid fields, you can choose:

• Allow — Sync the event with a warning.
• Block — Prevent the event from syncing.

These settings apply to both event properties and context fields.