Events and Automations

Track custom events to start and resume automations

Use the Events API to record product or lifecycle activity from your app. Events can start published automations and resume “Wait for event” steps for the matching contact.

SDK method

noketa.events.track(payload: TrackEventRequest): Promise<TrackEventResponse>

HTTP

POST /api/v1/events

Authenticate with the Noketa-Secret header set to your organization API key, or with a valid session cookie when calling from the browser.

Request body

Field	Type	Required	Description
`event`	`string`	Yes	Event key, e.g. `product.purchased`
`email`	`string?`	No	Contact email. Used to find or create the contact
`contactId`	`string?`	No	Existing Noketa contact ID. Takes precedence over `email`
`attributes`	`ContactAttributes?`	No	Merged into the contact when `email` is used
`metadata`	`Record<string, unknown>?`	No	Stored on the event and passed to matching automation runs

Provide either contactId or email. When only email is provided, Noketa upserts the contact before tracking the event. If that creates a new contact, contact.created automations also run.

Response

{
  "message": "Event tracked",
  "eventId": "<uuid>",
  "contactId": "<uuid>",
  "contactAction": "matched",
  "triggered": 1,
  "completedWaitpoints": 0,
  "failed": 0
}

Example

import { Noketa } from "noketa";

const noketa = new Noketa(process.env.NOKETA_API_KEY!);

await noketa.events.track({
  event: "product.purchased",
  email: "person@example.com",
  attributes: {
    first_name: "Jane",
    properties: {
      plan: "pro",
    },
  },
  metadata: {
    orderId: "order_123",
    amount: 4900,
  },
});

Event keys

Event keys may contain letters, numbers, dots, underscores, and hyphens. Built-in keys include contact.created; custom keys are automatically added to your organization’s automation event list when tracked.