Webhook

Publishing your tracking plan to a Webhook

Introduction

The Webhook integration is a way to get your updated Tracking Plan distributed to an endpoint of your choice. This happens when a branch is merged or when the publish button is clicked in the integration interface.

Configure the Webhook integration

Webhook URL

To enable the Webhook integration you need to configure it with a URL where you want the updated tracking plan to be delivered.

The Tracking Plan will be delivered with a POST request containing the Tracking Plan on a JSON format. The only requirement for this endpoint is to return a 200 response status code when it has successfully received the tracking plan.

Payload Format

Currently there are four different payload formats you can choose from for the webhook: Snowplow Schemas, Avo Json, NDJSON, and Json Schema (default).

💡 To see a preview of the exact Webhook payload in your Avo workspace choose Publishing in the sidebar, then pick your Webhook from the menu and expand the Payload preview section

Snowplow Schemas

Json containing a Snowplow Schema for every event included in the Publishing integration. These schemas can for example be used to integrate Avo with Snowplow Iglu.

You can provide your own vendor value via the “Vendor” input in the publishing integration config.

Attribute	Type	Description
eventSchemas	array(Snowplow Event Schema)	Schema for every event in your tracking plan, following the Snowplow Schema format
contextSchemas	array(Snowplow Context Schema)	Schema for every Snowplow context in your tracking plan, following the Snowplow Schema format
context	{ publishInfo: PublishInfo }	Metadata about the webhook call

Avo Json

Json representation of the state of your entire Avo workspace. Currently behind a feature flag. Contact us to enable.

Attribute	Type	Description
model	Avo Model	Json representation of your entire Avo workspace
context	{ publishInfo: PublishInfo }	Metadata about the webhook call

Json Schema (default)

Json representation of your tracking plan, following the Json Schema standard. Example payload can be found here

Attribute	Type	Description
name	string	The name of your Avo workspace
events	array(Event)	Array of Tracking Plan events
metrics	{ metricId: Metric … }	Objet where each Tracking Plan metric is a field, keys are metric ids
sources	{ sourceId: Source … }	Objet where each Tracking Plan source is a field, keys are source ids
destinations	{ destinationId: Destination … }	Objet where each Tracking Plan destination is a field, keys are destination ids
categories	{ categoryId: Category … }	Objet where each Tracking Plan metric is a field, keys are category ids
context	{ publishInfo: PublishInfo }	Metadata about the webhook call

Event Model

Attribute	Type	Description
id	string	Event id
name	string	Event name
eventType	enum: [“event”, “variant”]	Indicates if this event is based on an event or an event variant
description	string	Event description and the list of triggers
rules	Rules	Event JSON rules
tags	array(string)	Array of all tags attached to event
categories	array(string)	Array of category ids this event is attached to
triggers	array({id, description, sourceIds, link, imageUrl})	Details about all triggers attached to event
sources	array({id, name, implementWithCodegen, destinations})	Details about all sources sending event
variantName	optional string	If the event is generated from an event variant, this field is provided, contains the event variant name
stakeholderDomains	optional array({ id, name, isOwner })	Key present if any event or variant has stakeholder domains. Array of all stakeholders attached to event or variant

💡

Each event variant is represented by a standalone event in the JSON payload. It will have the same name, as the base event. Additionally, it will have the variantName field included, with the event variant name defined in the Avo Tracking Plan. You can distinguish an event, that is generated from a variant, from a base/standalone event, by checking the eventType field. The eventType of events that are generated from variants is variant, while regular events have it as event.

Stakeholder Domain Model

Attribute	Type	Description
id	string	Stakeholder team id
name	string	Stakeholder team name
isOwner	bool	Flag that indicates that the stakeholder team owns the event, event variant, or property

Rules Model

Attribute	Type	Description
properties	PropertiesRule	Properties JSON rules
nameMappings	array(NameMapping)	Name mappings defined for given event

PropertiesRule Model

Attribute	Type	Description
properties	array(PropertyRule)	Property JSON rules

PropertyRule Model

Attribute	Type	Description
description	string	Property description
type	string	Property type
tags	array(string)	Array of all tags attached to property
stakeholderDomains	array(StakeholderDomain)	Array of stakeholder domains associated with this property
nameMappings	array(NameMapping)	Name mappings defined for given property
?const	Depends on the property type	Pinned property value
?enum	array(string)	Allowed enum values
?operations	array(string)	Array of property ops, e.g. “SnowplowContext”
?pattern	string	Regex pattern for string type properties

NameMapping Model for regular workspaces

Attribute	Type	Description
name	string	New mapped name
destinationId	string	Either a destination id for which this event/property mapping applies, or “all”, meaning that this event/property mapping applies to all destinations

NameMapping Model for global workspaces in an Organization

Attribute	Type	Description
name	string	New mapped name
workspaceId	string	Either a workspace id for which this event/property mapping applies, or “all”, meaning that this event/property mapping applies to all local workspace in the Organization

Metric Model

Attribute	Type	Description
id	string	Metric id
name	string	Metric name
description	string	Metric description
categories	array(string)	Category ids where this metric is included
type	string	One of Proportion / EventSegmentation / Funnel / Retention
items	array of Nested Metric items	Event descriptions

Nested Metric Items

Nested Event Model

Attribute	Type	Description
eventId	string	Event id
where	array(whereFilter)	Array of where filters
groupBy	array(groupByFilter)	array of objects containing property ids to group by

Nested Event Variant Model

Attribute	Type	Description
variantIdentifier	object	Object of Base Event id and Variant id
where	array(whereFilter)	Array of where filters
groupBy	array(groupByFilter)	array of objects containing property ids to group by

groupByFilter

Attribute	Type	Description
propertyId	string	property Id being used in group filter

Where filter

Attribute	Type	Description
propertyId	string	property id
operation	string	binary operation as string
values	array(t)	array of values of the same type

Source Model

Attribute	Type	Description
id	string	Source id
name	string	Source name
programmingLanguage	string	Name of programming language (e.g. “JavaScript”, “Python”)
developmentPlatform	string	Name of development platform (e.g. “Web”, “Android”)
destinations	array(string)	Destination ids where this source sends data to

Destination Model

Attribute	Type	Description
id	string	Destination id
name	string	Destination name
type	string	Name of the provider (e.g. “Segment”, “Mixpanel”) where the data is sent to if managed by Avo, “Custom” otherwise.

Category Model

Attribute	Type	Description
id	string	Category id
name	string	Category name
description	string	Category description
metrics	array(string)	Metric ids belonging this category
events	array(string)	Event ids belonging this category

PublishInfo Model

Attribute	Type	Description
branchId	string	Branch id
branchName	string	Branch name
integrationId	string	Id of the publish integration (consistently the same for this integration)
integrationName	string	Name of the publish integration (seen in Tracking Plan -> publishing -> ‘IntegrationName’)
publishDate	Date string	Timestamp when the webhook was triggered
publishMethod	{ “type”: type }	Description of the publish method, type can be “Manual” and “BranchMerge”
lastUpdateId	id	Unique identifier of the last modification made to the tracking plan before the generation of this schema
lastUpdateDate	Date string	Time of the last modification made to the tracking plan before the generation of this schema
organization	Organization Model	Provided if the workspace being published belongs to an organization

Organization Model

Attribute	Type	Description
organizationId	string	Organization id
globalWorkspaceIds	array(string)	List of all global workspaces in Organization
localWorkspaceIds	array(string)	List of all local workspaces in Organization
workspaceType	string	Describes the type of the workspace being published, “local” or “global”

NDJSON

Newline-delimited JSON representation of your tracking plan. The top-level payload is a small JSON envelope containing two string fields, where each string is NDJSON: one JSON object per line.

Envelope

Attribute	Type	Description
events	string (NDJSON)	NDJSON where each line is an Events row described below
properties	string (NDJSON)	NDJSON where each line is an Event Properties row described below
context	{ publishInfo: PublishInfo }	Optional. Metadata about the webhook call

Events NDJSON line schema

Attribute	Type	Description
event_id	string	Event id
event_name	string	Event name
event_type	enum: [“event”, “variant”]	Whether this row represents a base event or a variant
variant_name	string or null	Variant name when `event_type` is `variant`, otherwise null
description	string or null	Event description, or null if empty
global_description	null	Reserved for future use
tags	array(string)	Tags attached to the event
categories	array(string)	Category names the event belongs to
actions	array(string)	Actions inferred from event types (camelCase)
stakeholder_domains	array(StakeholderDomain)	Stakeholder domains for the event (see model below)
sources	array(Source)	Included sources for the event
name_mapping	array(NameMapping)	Event-level name mappings per destination
rules	Rules	Per-property details for this event (see below)

Source: { id: string, name: string, implement_with_codegen: bool, destinations: array(string) }
NameMapping: { name: string, destination_id: string } (destination_id can be "all")
StakeholderDomain: { id: string, name: string, is_owner: bool }
Rules: { properties: array(Property), user_properties: array(Property), group_properties: array(Property) }
Property: { property_id: string, property_name: string, name_mapping: array(NameMapping), required: bool }

Properties NDJSON line schema

Each line describes a property scoped to an event, user, or group.

Attribute	Type	Description
event_id	string	Event id
event_name	string	Event name
property_id	string	Property id
property_name	string	Property name
property_scope	enum: [“event”, “user”, “group”]	Whether the property is event, user or a group property
required	bool	Whether the property is required for this event (considering included sources)
description	string or null	Property description, or null if empty
tags	array(string)	Tags attached to the property
name_mapping	array(NameMapping)	Property-level name mappings per destination for this event
group_type_id	string or null	Group type id if `property_scope` is `group`, otherwise null
is_system_property	bool	Whether the property is a system property
type	string or null	Base JSON Schema type (e.g. `integer`, `number`, `string`, `boolean`, `object`), or `array` if the property is a list; null if not applicable
enum	array(string) or null	Allowed values if the property is an enum for this event
minimum	number or null	Minimum numeric value if defined
maximum	number or null	Maximum numeric value if defined
regex	string or null	Regex constraint (event override preferred; falls back to property rule)
stakeholder_domains	array(StakeholderDomain)	Stakeholder domains for this property

Snowplow Data Structures Exporting