> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/webhooks/webhook-events.md).

# Webhook Event Types

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](/developer-guide/classic-api/webhooks.md).

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:**

```javascript
{
    // 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
}
```

{% hint style="success" %}
**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.
{% endhint %}

## Post-Processing Events

### `conversation-post-processing-complete`

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

{% hint style="info" %}
**Asynchronous processing.** Post-processing runs after conversations end, performing deep analysis without blocking the user experience.
{% endhint %}

**Payload structure:**

```javascript
{
    // 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 |

<details>

<summary>Processing architecture</summary>

* **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.

</details>

See [Memory Architecture & API Mapping](/developer-guide/operations/reference/memory-architecture.md) 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:**

```javascript
{
    // 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](/developer-guide/classic-api/webhooks.md): destinations, delivery, retries, and signature verification
* [Common Patterns: Webhook-Driven Memory Sync](/developer-guide/operations/reference/common-patterns.md#3-webhook-driven-memory-sync): a runnable handler example


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/webhooks/webhook-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.