# Webhooks

Shade sends webhook events to notify your application when resources are created, updated, or deleted across your workspace. You can subscribe to specific event types to build integrations, sync external systems, or trigger custom workflows.

### Accessing Webhooks from the App and Opening the Webhooks Dashboard

Shade offers a full webhooks dashboard that you can easily configure and manage all of your webhook endpoints.

<figure><img src="/files/91Y4lmkHl1qMrpIDc9qH" alt=""><figcaption></figcaption></figure>

### Creating an Initial Webhook Response Endpoint

Once you have opened the dashboard, you can configure a new endpoint under the "Endpoints" section. From there, you can subscribe to any of our events and send the output to your endpoint URL for further processing.&#x20;

<figure><img src="/files/gj1QbYorm68ogXtrcU2V" alt=""><figcaption></figcaption></figure>

### Event Format

Every webhook delivers a JSON payload with a consistent envelope structure:

```json
{
  "event_type": "resource_type.action",
  "resource": {
    "type": "resource_type",
    "id": "uuid"
  },
  "user": {
    "id": "uuid",
    "email": "jane@example.com",
    "name": "Jane Smith"
  },
  "workspace": {
    "id": "uuid",
    "name": "My Workspace",
    "domain": "myworkspace"
  },
  "drive": {
    "id": "uuid",
    "name": "My Drive",
    "identifier": "my-drive"
  },
  "payload": {}
}
```

### Current Running List of Planned / Supported Webhooks

{% hint style="info" %}
You can take a look at all of the endpoints available via the Webhooks dashboard accesible via our app and heading to `Event Catalog`
{% endhint %}

| Field        | Type             | Description                                                                            |
| ------------ | ---------------- | -------------------------------------------------------------------------------------- |
| `event_type` | `string`         | The event identifier in `resource_type.action` format.                                 |
| `resource`   | `object`         | The resource type and ID the event relates to.                                         |
| `user`       | `object \| null` | The user who performed the action. `null` for system-initiated events (e.g. indexing). |
| `workspace`  | `object`         | The workspace the event occurred in.                                                   |
| `drive`      | `object \| null` | The drive the event occurred in. `null` for workspace-level events.                    |
| `payload`    | `object`         | The full resource data at the time of the event. Fields vary by resource type.         |

***

### Available Events

#### Assets

Events triggered by file system changes detected during drive indexing. The `user` field is `null` for these events since they are system-initiated.

| Event            | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| `asset.created`  | A new file was detected in the drive.                                          |
| `asset.modified` | An existing file was modified.                                                 |
| `asset.moved`    | A file was moved or renamed. `payload` includes `path` and `to_path`.          |
| `asset.deleted`  | A file was deleted from the drive.                                             |
| `asset.uploaded` | A file was uploaded to the drive.                                              |
| `asset.updated`  | A metadata attribute was updated on an asset. Fired once per attribute change. |

#### Asset Processing

Events fired when background processing jobs complete. The `user` field is `null` for these events.

| Event                     | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `preview.completed`       | Preview image generation finished for an asset.  |
| `proxy.completed`         | Video proxy generation finished for an asset.    |
| `audio_proxy.completed`   | Audio proxy generation finished for an asset.    |
| `transcription.completed` | Transcription finished for an audio/video asset. |

#### Collections

| Event                      | Description                                                 |
| -------------------------- | ----------------------------------------------------------- |
| `collection.created`       | A new collection was created (includes duplications).       |
| `collection.updated`       | A collection's name, description, or settings were changed. |
| `collection.deleted`       | A collection was deleted.                                   |
| `collection.items_added`   | Assets were added to a collection.                          |
| `collection.items_removed` | Assets were removed from a collection.                      |

#### Comments

| Event                | Description                                     |
| -------------------- | ----------------------------------------------- |
| `comment.created`    | A new comment or reply was created on an asset. |
| `comment.updated`    | A comment's text was edited.                    |
| `comment.deleted`    | A comment was deleted.                          |
| `comment.resolved`   | A comment thread was marked as resolved.        |
| `comment.unresolved` | A resolved comment thread was reopened.         |
| `comment.reacted`    | A reaction was added to a comment.              |

#### Public Links

| Event                 | Description                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| `public_link.created` | A new public share link was created.                                                               |
| `public_link.updated` | A public share link's settings were changed (permissions, password, expiration, view limit, etc.). |
| `public_link.deleted` | A public share link was removed.                                                                   |

#### Drive Members

| Event                  | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| `drive_invite.created` | A user was invited to a drive or granted access to a path. |
| `drive_invite.updated` | A user's drive role or path permissions were changed.      |
| `drive_invite.deleted` | A user was removed from a drive or lost access to a path.  |

#### Workspace Members

| Event                      | Description                            |
| -------------------------- | -------------------------------------- |
| `workspace_invite.created` | A user was invited to the workspace.   |
| `workspace_invite.updated` | A user's workspace role was changed.   |
| `workspace_invite.deleted` | A user was removed from the workspace. |

#### Drives

| Event           | Description                               |
| --------------- | ----------------------------------------- |
| `drive.created` | A new drive was created in the workspace. |


---

# Agent Instructions: 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:

```
GET https://academy.shade.inc/developers/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.