Skip to main content
Project events let you store timestamped data points in Kapso, then inspect them later or use them to trigger workflows.
Project events are durable custom records, not workflow execution events. Workflow execution events are the step-by-step logs used to debug a workflow run.
Use events for product moments and derived data you want to keep over time:
  • lead.qualified
  • checkout.abandoned
  • conversation.csat_scored
  • support.intent_detected
  • handoff.quality_reviewed
Events are append-only records during normal operation. Deleting an event definition also permanently deletes its recorded events. They work well for facts, scores, labels, outcomes, and workflow outputs that should be queryable later. Examples:
  • Store an LLM-generated CSAT score after a conversation ends
  • Save the detected intent, language, or urgency for a support conversation
  • Record whether a handoff was successful
  • Keep lead scoring outputs from a qualification workflow
  • Store a quality review result for future analysis

​
Emit an event

Response:
conversation_id is optional. Include it when the event belongs to a WhatsApp conversation, so workflows and webhooks can keep that context.

​
Event format

Event names must be lowercase and can be up to 128 characters:
Properties must be a flat JSON object. Values can be strings, numbers, booleans, or null. Limits:
  • Event name: 128 characters
  • Properties: 25 keys
  • Property key: 64 characters
  • String property value: 1 KB
  • Total properties payload: 8 KB
  • occurred_at: no more than 5 minutes in the future
Events older than your project’s event retention window are rejected.

​
Manage event definitions

Event definitions describe an event name, its meaning, and its expected property schema. Use the Platform API to manage them:
  • GET /platform/v1/event-definitions lists active definitions, ordered by name. Add ?include_archived=true to include archived definitions.
  • POST /platform/v1/event-definitions creates a definition or updates the editable metadata of an existing definition with the same name. Upserting an archived definition restores it.
  • GET /platform/v1/event-definitions/:id retrieves one definition.
  • PATCH /platform/v1/event-definitions/:id updates metadata. Set archived to true to archive a definition or false to restore it.
  • DELETE /platform/v1/event-definitions/:id queues permanent deletion of the definition and all events recorded with it. The endpoint returns 202 Accepted; deletion happens asynchronously and cannot be undone. While deletion is pending, new events with the same name are rejected.

​
Archive and restore

Archive a definition without deleting its recorded events:
Archived definitions retain their historical events and expose archived_at, but are hidden from default definition lists, event tools, and workflow selectors. Restore one by setting archived to false, or by creating a definition with the same name. Archiving does not prevent the Events API from recording another event with the same name.

​
Permanently delete

Delete a definition and all of its recorded events:
Deletion is asynchronous. A successful request returns 202 Accepted, permanently removes the definition and its recorded events, and cannot be undone.

​
Query events

Available filters:
  • name
  • conversation_id
  • occurred_after
  • occurred_before
Results are ordered newest first. Include limit to use cursor pagination with after and before.

​
Use in workflows

Workflows can start from project events and emit them as part of their execution. See Use project events in workflows for trigger configuration, workflow context, limits, and the available emission methods.

​
Webhooks

Project-scoped webhooks can subscribe to project.event to receive emitted events. project.event is only available on project webhooks. Phone-number webhooks do not receive custom project events. Subscribing a webhook to project.event requires project events to be available on your plan.

​
Plans and usage

Project events are plan-gated and counted against your monthly project event allowance. When project events are not available on your plan, creating or updating event definitions and project.event webhook subscriptions returns 402 Payment Required. When the allowance is exceeded, event emission returns 402 Payment Required unless your plan allows metered overage.