> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.dumgum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Webhook

DumGum's AI automatically learns and memorizes facts about Users and Personas during conversations. The Memory Webhook lets you receive real-time notifications whenever the AI updates its memory, so you can keep your own systems in sync.

When configured, every time a conversation produces memory changes (new facts learned, outdated facts removed), DumGum sends an HTTP POST to your endpoint with the details.

# Configuration

The Memory Webhook is configured through your project's Content Creation configuration, either via the API or directly from the [Customer Dashboard](https://dash.dumgum.ai). Three fields control the behavior:

| Field                        | Type     | Required | Default      | Description                                   |
| ---------------------------- | -------- | -------- | ------------ | --------------------------------------------- |
| `memoryWebhookUrl`           | `string` | Yes      | None         | The URL that will receive webhook payloads    |
| `memoryWebhookCustomHeaders` | `object` | No       | `{}`         | Custom HTTP headers included in every request |
| `memoryWebhookMode`          | `string` | No       | `FULL_STATE` | Delivery mode: `FULL_STATE` or `CHANGES_ONLY` |

```json theme={null}
{
  "memoryWebhookUrl": "https://your-server.com/webhooks/memory",
  "memoryWebhookCustomHeaders": {
    "X-Api-Key": "your-secret-key"
  },
  "memoryWebhookMode": "CHANGES_ONLY"
}
```

# Delivery Modes

## FULL\_STATE (default)

Every time the AI updates its memory, we send **the complete current memory state** for that User/Persona pair. Just replace whatever you have stored locally with what we send.

**Event:** [`memory.updated`](/api-reference/content-creation/webhooks/events/memory-updated)

<Tip>
  Best for simple "replace all" integrations where you don't need to track individual additions or deletions.
</Tip>

## CHANGES\_ONLY

We send only what changed: which memories were **added** and which were **deleted**. More efficient for high-volume integrations applying incremental updates.

**Event:** [`memory.changed`](/api-reference/content-creation/webhooks/events/memory-changed)

<Tip>
  Best when you maintain your own memory store and want to apply incremental diffs instead of replacing the entire state.
</Tip>

# When Are Webhooks Triggered?

Webhooks are triggered whenever the AI processes a conversation and its memory system detects changes, typically when a User sends a message and the AI replies.

<Note>
  Webhooks are only sent when memory actually changes. If a conversation is processed but no new facts are learned and no existing memories are updated or removed, no webhook is sent.
</Note>

# HTTP Request Details

| Property           | Value                                         |
| ------------------ | --------------------------------------------- |
| **Method**         | `POST`                                        |
| **Content-Type**   | `application/json`                            |
| **User-Agent**     | `dg2-api`                                     |
| **Custom Headers** | As configured in `memoryWebhookCustomHeaders` |

## Retry Behavior

If your endpoint returns a non-2xx status code, or if the connection fails or times out, we automatically retry:

* **Retry interval:** 15 seconds
* **Maximum retries:** 40 attempts

<Warning>
  Your endpoint should return a `2xx` status code as quickly as possible. If processing is slow, accept the webhook and handle it asynchronously to avoid timeouts.
</Warning>

# Quick Start

1. **Set your webhook URL** in your project configuration.
2. **Choose a mode:** `FULL_STATE` for simplicity, `CHANGES_ONLY` for incremental updates.
3. **Add custom headers** (optional): include authentication headers to verify incoming requests.
4. **Handle the payload:** see the event reference for [`memory.updated`](/api-reference/content-creation/webhooks/events/memory-updated) or [`memory.changed`](/api-reference/content-creation/webhooks/events/memory-changed).
5. **Return 2xx:** respond with a success status code to acknowledge receipt.