Webhook Event Types

Payload reference for each Classic API webhook event type: api-key-expiration-soon, conversation-post-processing-complete, and agent-framework-resource-updated.

This page is the payload reference for every event a Classic API webhook destination can receive. Use it to write handlers that parse each event's fields correctly, and to decide which event types your destination should subscribe to. For destination setup, delivery behavior, and signature verification, see Webhook Management.

Every payload carries a type field identifying the event. Event names are hyphenated (for example, conversation-post-processing-complete).

API Key Events

api-key-expiration-soon

Fires when an API key is approaching its expiration date. Notifications arrive at 14, 7, and 1 day before expiration, giving you time to rotate keys before service is disrupted.

Payload structure:

{
    // The webhook event type
    type: "api-key-expiration-soon",

    // Your organization's unique identifier
    org_id: string,

    // The API key that is expiring
    api_key_id: string,

    // Human-readable name of the expiring API key (may be null)
    api_key_name: string | null,

    // When the API key will expire (UTC datetime)
    expiration_time: string,

    // Unique key for deduplication across retries
    idempotent_key: string
}

Proactive key rotation. Subscribe to this event to automate key rotation. Create a new API key, transition your applications, and revoke the expiring key before it becomes invalid.

Post-Processing Events

conversation-post-processing-complete

Fires when asynchronous post-processing analysis completes for a conversation.

Asynchronous processing. Post-processing runs after conversations end, performing deep analysis without blocking the user experience.

Payload structure:

{
    // The webhook event type
    type: "conversation-post-processing-complete",

    // The specific post-processing operation that completed
    post_processing_type: "generate-user-models" | "extract-memories" | "compute-metrics",

    // Unique identifier for the conversation that was analyzed
    conversation_id: string,

    // Your organization's unique identifier
    org_id: string,

    // Unique key for deduplication across retries
    idempotent_key: string
}

Post-processing types:

Type	Description	Purpose
generate-user-models	Builds the episodic (L2) model and updates the global (L3) user model	Enhanced personalization
extract-memories	Stores key information as L1 observations	Future context recall
compute-metrics	Calculates performance metrics	Quality and effectiveness measurement

Processing architecture

• Live sessions handle real-time interaction.
• Post-processing performs deep analysis after a conversation.
• No blocking. The user experience stays responsive.
• Async updates. Memories, models, and metrics are updated in the background.

See Memory Architecture & API Mapping for how to react to these events and fetch the updated memory layers.

Agent Framework Resource Events

agent-framework-resource-updated

Fires when an agent framework resource is created, updated, or deleted. Subscribe to keep external systems in sync with configuration changes made in the platform.

Payload structure:

{
    // The webhook event type
    type: "agent-framework-resource-updated",

    // Your organization's unique identifier
    org_id: string,

    // Unique key for deduplication across retries
    idempotent_key: string,

    // When the change occurred (UTC datetime)
    timestamp: string,

    // Discriminated object describing the resource that changed
    change_event: {
        // The kind of resource that changed (see table below)
        type: string,

        // The user who made the change
        updated_by_user_id: string,

        // The organization the change was made in
        updated_by_org_id: string,

        // The identifier of the changed resource (field name varies by type,
        // e.g. agent_id, state_machine_id)
        // ...resource ID field...

        // The kind of change (created, updated, or deleted; varies by event)
        change_type: string
    }
}

Resource types (change_event.type):

The change_event.type field uses the API resource name. The table below maps each value to its platform-facing concept.

change_event.type (API)	Platform concept
agent	Agent
agent-version	Agent version
state-machine	Context Graph
state-machine-version	Context Graph version
dynamic-behavior-set	Dynamic Behaviors
dynamic-behavior-set-version	Dynamic Behaviors version
service	Service
service-version	Service version
metric	Metric
metric-version	Metric version
tool	Action
tool-version	Action version

Related Pages

• Webhook Management: destinations, delivery, retries, and signature verification
• Common Patterns: Webhook-Driven Memory Sync: a runnable handler example