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

# Webhook events

> Every webhook event ReyGrid sends, and what's inside it.

Pick the events an endpoint receives when you create or edit it. Each event is sent as the `data` of the [event envelope](/rest-api/webhooks/overview#request-format).

| Event | When it's sent |
| - | - |
| [`chat.completed`](#chat-completed) | An API chat request succeeded |
| [`chat.failed`](#chat-failed) | An API chat request failed |
| [`agent.created`](#agent-created) | An agent was created |
| [`agent.updated`](#agent-updated) | An agent's name, model or instructions changed |
| [`agent.deleted`](#agent-deleted) | An agent was deleted |
| [`source.added`](#source-added) | Knowledge was added to an agent |
| [`source.deleted`](#source-deleted) | Knowledge was removed from an agent |
| [`credits.low`](#credits-low) | Your credits dropped below 20% |

You also receive a [`ping`](#ping) event when you select **Send test** in the console, whatever events the endpoint subscribes to.

<Note>
  Events are sent to the endpoints of the account that **owns** the resource. In a team workspace, a teammate's change to your agent is sent to your endpoints.
</Note>

## Chat

Sent for `POST /agents/{AgentId}/chat` requests made with an API key. Messages sent from the console playground don't trigger chat events.

### chat.completed

```json theme={"system"}
{
  "id": "evt_6f1c2a9e4b7d03a58c21e0f4",
  "type": "chat.completed",
  "created": "2026-10-05T09:24:13.512Z",
  "data": {
    "agent": { "id": "{AgentId}" },
    "conversationId": "c0f3…",
    "userId": null,
    "credits": 0.5,
    "apiKey": "production"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `agent.id` | string | The agent that answered |
| `conversationId` | string \| null | The conversation, when the request used one |
| `userId` | string \| null | Your end-user ID, when the request sent `userId` |
| `credits` | number | Credits charged for the request |
| `apiKey` | string | The **name** of the API key used (never the key itself) |

### chat.failed

Same fields as `chat.completed`. `credits` is `0`: failed requests are refunded.

```json theme={"system"}
{
  "type": "chat.failed",
  "data": {
    "agent": { "id": "{AgentId}" },
    "conversationId": null,
    "userId": null,
    "credits": 0,
    "apiKey": "production"
  }
}
```

## Agents

### agent.created

```json theme={"system"}
{
  "type": "agent.created",
  "data": { "agent": { "id": "{AgentId}", "name": "Support" } }
}
```

### agent.updated

Sent when the agent's name, model or instructions are saved. `agent.name` is the new name.

```json theme={"system"}
{
  "type": "agent.updated",
  "data": { "agent": { "id": "{AgentId}", "name": "Support desk" } }
}
```

### agent.deleted

The agent, its knowledge and its conversations are gone by the time you receive this event.

```json theme={"system"}
{
  "type": "agent.deleted",
  "data": { "agent": { "id": "{AgentId}", "name": "Support desk" } }
}
```

## Knowledge

`source` describes what was added or removed: the title of a text entry, the question of a Q\&A pair, a file name, or a website URL.

### source.added

```json theme={"system"}
{
  "type": "source.added",
  "data": {
    "agent": { "id": "{AgentId}", "name": "Support desk" },
    "source": "Refund policy"
  }
}
```

<Info>
  Crawling a website sends **one** `source.added` event for the whole crawl, with the URL you submitted as `source`.
</Info>

### source.deleted

```json theme={"system"}
{
  "type": "source.deleted",
  "data": {
    "agent": { "id": "{AgentId}", "name": "Support desk" },
    "source": "pricing.pdf"
  }
}
```

## Billing

### credits.low

Sent once when your remaining credits drop below **20%** of your last top-up or monthly allowance. It's sent again only after your credits are refilled and run low again.

```json theme={"system"}
{
  "type": "credits.low",
  "data": { "credits": 182.5, "threshold": 1000 }
}
```

| Field | Type | Description |
| - | - | - |
| `credits` | number | Credits remaining when the event was sent |
| `threshold` | number | The level that triggered the alert (20% of the last refill) |

## Test

### ping

Sent by **Send test** in the console. Use it to check that your endpoint is reachable and verifies signatures correctly.

```json theme={"system"}
{
  "id": "evt_2b9c04e81f6a5d7c3e10a9b2",
  "type": "ping",
  "created": "2026-10-05T09:30:00.000Z",
  "data": { "message": "Test event from ReyGrid" }
}
```

<Tip>
  New event types may be added over time. Ignore types your handler doesn't know instead of returning an error.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.