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

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Event types

> Every event outbound webhooks can send, the envelope each one arrives in, the fields in its data and the JSON Schema that describes it, with a full example.

Each event type names something that happened in your workspace. You choose the types an endpoint receives when you set it up, and you can change them later.

Each event also has a reference page with every field, the signature headers and an example request: [app.created.v1](/developers/references/outbound-webhooks/events/app-created-v1), [app.published.v1](/developers/references/outbound-webhooks/events/app-published-v1), [app.unpublished.v1](/developers/references/outbound-webhooks/events/app-unpublished-v1), [app.deleted.v1](/developers/references/outbound-webhooks/events/app-deleted-v1), [app.restored.v1](/developers/references/outbound-webhooks/events/app-restored-v1), [builder.turn\_started.v1](/developers/references/outbound-webhooks/events/builder-turn-started-v1), [builder.turn\_ended.v1](/developers/references/outbound-webhooks/events/builder-turn-ended-v1) and [webhook.test.v1](/developers/references/outbound-webhooks/events/webhook-test-v1).

***

## The envelope

Every request body is a [CloudEvents 1.0](https://cloudevents.io/) JSON document. The same attributes appear on every event, and `data` holds the fields for that event type.

| Attribute | Value |
| - | - |
| `specversion` | Always `1.0`. |
| `id` | The event's unique ID, such as `evt_68c1d2e3f4a5b6c7d8e9f0a1`. It's the same on every retry, so use it to ignore duplicates. |
| `source` | Your workspace, as `https://base44.com/workspaces/{workspace_id}`. |
| `type` | The event type, such as `app.created.v1`. |
| `subject` | What the event is about, as `apps/{app_id}`. |
| `time` | When the change happened, in UTC. |
| `datacontenttype` | Always `application/json`. |
| `dataschema` | The URL of the JSON Schema for `data`. |
| `authtype` | Who made the change: `user`, `service_account`, `api_key` or `system`. |
| `authid` | The ID of whoever made the change, when there is one. |
| `data` | The event's own fields, listed below. |

Every timestamp, in `time` and in `data`, uses one format: `2026-09-01T10:15:30.123Z`.

***

## App events

These 5 events let you keep a copy of each app's state in your own system. Every one carries the same 3 identifying fields, plus a timestamp for the change.

| Field | Description |
| - | - |
| `app_id` | The app the event is about. |
| `workspace_id` | The workspace the app belongs to. |
| `owner_id` | The Base44 ID of the app's current owner. |

Events carry IDs only. App names, app content and personal details are never included.

| Event type | Sent when | Extra fields |
| - | - | - |
| `app.created.v1` | An app is created, including by cloning or importing. | `app_type`, `created_at` |
| `app.published.v1` | A version of an app goes live. | `published_version`, `published_at` |
| `app.unpublished.v1` | An app is taken offline. | `unpublished_at` |
| `app.deleted.v1` | An app is moved to trash. | `deleted_at` |
| `app.restored.v1` | An app is restored from trash. | `restored_at` |

`app_type` is one of `user_app` (an app), `user_agent` (a Superagent), `user_game` (a game) or `imported_app` (an app imported from a repository).

<Warning>
  `app.deleted.v1` means the app moved to trash, not that it's gone. It can still be restored, and `app.restored.v1` tells you when it is. Don't delete your own copy of the app's data when you receive it.
</Warning>

### Example: app.created.v1

A complete request body for a new app:

```json theme={null}
{
  "specversion": "1.0",
  "id": "evt_68c1d2e3f4a5b6c7d8e9f0a1",
  "source": "https://base44.com/workspaces/68a1b2c3d4e5f6a7b8c9d0e1",
  "type": "app.created.v1",
  "subject": "apps/68b0c1d2e3f4a5b6c7d8e9f0",
  "time": "2026-09-01T10:15:30.123Z",
  "datacontenttype": "application/json",
  "dataschema": "https://base44.com/webhooks/schemas/app.created.v1.json",
  "authtype": "user",
  "authid": "6899aabbccddeeff00112233",
  "data": {
    "app_id": "68b0c1d2e3f4a5b6c7d8e9f0",
    "workspace_id": "68a1b2c3d4e5f6a7b8c9d0e1",
    "owner_id": "6899aabbccddeeff00112233",
    "app_type": "user_app",
    "created_at": "2026-09-01T10:15:30.123Z"
  }
}
```

***

## Builder events

These 2 events tell you when the AI builder works on a message sent to an app, so a platform that sends messages from its own server doesn't have to hold the request open or poll for the result. A turn is one message and everything the builder does in response, including the automatic error fixes it runs before it replies.

Both carry the 3 identifying fields of the app events, plus:

| Field | Description |
| - | - |
| `message_id` | The message that started the turn: the ID returned when you sent it. Both events of a turn carry the same one. |
| `conversation_id` | The conversation the message belongs to, when there is one. |
| `started_at` | When the builder started working on the message. |
| `continues_message_id` | Set when this turn continues one that was interrupted: the `message_id` of that turn. Follow it back to add up how long the whole response took. |

| Event type | Sent when | Extra fields |
| - | - | - |
| `builder.turn_started.v1` | The builder picks the message up. A message sent while another turn runs waits until then. | |
| `builder.turn_ended.v1` | The turn ends. Each turn ends once. | `status`, `ended_at` |

`status` is one of:

* `finished`: the builder replied and has nothing pending.
* `waiting_for_user_input`: the builder stopped to ask something, such as a clarifying question or a plan to approve. It continues when the next message answers it.
* `failed`: the turn hit an error.
* `cancelled`: the turn was stopped before it ended.
* `interrupted`: the builder was interrupted, for example by a restart. It continues in a new turn whose `continues_message_id` is this turn's `message_id`.

***

## The activation test

Base44 sends `webhook.test.v1` when an endpoint is activated or tested. You can't select it, and it's sent to every endpoint that's being activated. Its `subject` is `endpoints/{endpoint_id}`.

| Field | Description |
| - | - |
| `endpoint_id` | The endpoint being activated. |
| `workspace_id` | The workspace the endpoint belongs to. |
| `sent_at` | When the test was sent. |
| `challenge` | Return this value in your response body to activate the endpoint. |

To learn how to answer it, see [Echoing the challenge](/developers/references/outbound-webhooks/get-started/setting-up-endpoints#echoing-the-challenge).

***

## JSON Schemas

Each event type has a JSON Schema for its `data`, at the URL in the event's `dataschema` attribute:

| Event type | Schema |
| - | - |
| `app.created.v1` | [app.created.v1.json](https://base44.com/webhooks/schemas/app.created.v1.json) |
| `app.published.v1` | [app.published.v1.json](https://base44.com/webhooks/schemas/app.published.v1.json) |
| `app.unpublished.v1` | [app.unpublished.v1.json](https://base44.com/webhooks/schemas/app.unpublished.v1.json) |
| `app.deleted.v1` | [app.deleted.v1.json](https://base44.com/webhooks/schemas/app.deleted.v1.json) |
| `app.restored.v1` | [app.restored.v1.json](https://base44.com/webhooks/schemas/app.restored.v1.json) |
| `builder.turn_started.v1` | [builder.turn\_started.v1.json](https://base44.com/webhooks/schemas/builder.turn_started.v1.json) |
| `builder.turn_ended.v1` | [builder.turn\_ended.v1.json](https://base44.com/webhooks/schemas/builder.turn_ended.v1.json) |
| `webhook.test.v1` | [webhook.test.v1.json](https://base44.com/webhooks/schemas/webhook.test.v1.json) |

A published schema never changes. When an event's fields change in a way that could break your receiver, Base44 adds a new version, such as `app.created.v2`, and keeps sending the old one to endpoints that selected it.

<Note>
  The [Audit Logs API](/developers/references/audit-logs-api/get-started/overview) has events with similar names, such as `app.created`. They're a separate record with their own fields, so the 2 can differ.
</Note>


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