# Webhooks
Webhooks let you automatically notify external services when specific events occur in your echo3D collection. When a configured event fires, echo3D sends an HTTP POST request with a JSON payload to your specified URL, enabling real-time integrations and automated workflows.
The Webhooks tab is located on the Workflows page.
### Creating a Webhook
To create a new webhook, navigate to the Webhooks tab and click the **Add Webhook** button. A dialog will appear with the following fields:
* **Name**: A name for your webhook (required).
* **URL**: The HTTPS endpoint that echo3D will call when a selected event is triggered (required). The URL must use HTTPS and cannot point to a private or localhost address.
* **Description**: An optional description of what the webhook is used for.
* **Set Webhook Trigger(s)**: One or more echo3D events that will trigger a POST request to your URL. Each trigger and its corresponding webhook payload are described in detail in the next section.
### Webhook Triggers & Payloads
Every webhook receives an HTTP POST with a JSON payload. The payload always has the same fields, listed below. Importantly, metadata keys/values are parallel arrays: metadataKeys\[i] corresponds to metadataValues\[i]. In the examples below, "color" maps to "red" and "size" maps to "large".
| Field | Type | Description |
| -------------- | --------- | ------------------------------------------------------ |
| event | string | The trigger that fired |
| apiKey | string | The API key of the collection |
| entryIds | string\[] | The affected entry/asset IDs (empty if not applicable) |
| metadataKeys | string\[] | The metadata keys involved (empty if not applicable) |
| metadataValues | string\[] | The metadata values involved (empty if not applicable) |
| statuses | string\[] | The statuses involved (empty if not applicable) |
| versionIds | string\[] | The version ID's involved (empty if not applicable) |
***
#### 1. Upload
Fired when a new asset is uploaded to the collection. Only one entryId is ever sent for this trigger.
```json
{
"event": "Upload",
"apiKey": "bold-sky-1234",
"entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
"metadataKeys": [],
"metadataValues": [],
"statuses": [],
"versionIds": []
}
```
#### 2. Processed
Fired when a new asset is uploaded to the collection and fully processed. Only one entryId is ever sent for this trigger.
```json
{
"event": "Processed",
"apiKey": "bold-sky-1234",
"entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
"metadataKeys": [],
"metadataValues": [],
"statuses": [],
"versionIds": []
}
```
#### 3. Edit
Fired when a new hologram is added to an existing asset (e.g. uploading a new file version for the same entry). Only one entryId is ever sent for this trigger.
```json
{
"event": "Edit",
"apiKey": "bold-sky-1234",
"entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
"metadataKeys": [],
"metadataValues": [],
"statuses": [],
"versionIds": []
}
```
#### 4. Delete
Fired when one or more assets are deleted from the collection. Note that entryIds may contain multiple IDs.
```json
{
"event": "Delete",
"apiKey": "bold-sky-1234",
"entryIds": [
"a1b2c3d4-5678-90ab-cdef-1234567890ab",
"f9e8d7c6-5432-10fe-dcba-0987654321fe"
],
"metadataKeys": [],
"metadataValues": [],
"statuses": [],
"versionIds": []
}
```
#### 5. CollectionMetadataAdd
Fired when metadata key-value pairs are added at the collection (project) level. entryIds is empty because this metadata applies to the entire collection, not specific assets.
```json
{
"event": "CollectionMetadataAdd",
"apiKey": "bold-sky-1234",
"entryIds": [],
"metadataKeys": ["category", "environment"],
"metadataValues": ["furniture", "indoor"],
"statuses": [],
"versionIds": []
}
```
#### 6. CollectionMetadataRemove
Fired when metadata key-value pairs are removed at the collection (project) level.
```json
{
"event": "CollectionMetadataRemove",
"apiKey": "bold-sky-1234",
"entryIds": [],
"metadataKeys": ["category", "environment"],
"metadataValues": ["furniture", "indoor"],
"statuses": [],
"versionIds": []
}
```
#### 7. AssetMetadataAdd
Fired when metadata key-value pairs are added to specific assets. All three list fields are populated: entryIds identifies the affected assets, and metadataKeys/metadataValues are the metadata that was added.
```json
{
"event": "AssetMetadataAdd",
"apiKey": "bold-sky-1234",
"entryIds": [
"a1b2c3d4-5678-90ab-cdef-1234567890ab",
"f9e8d7c6-5432-10fe-dcba-0987654321fe"
],
"metadataKeys": ["color", "size"],
"metadataValues": ["red", "large"],
"statuses": [],
"versionIds": []
}
```
#### 8. AssetMetadataRemove
Fired when metadata key-value pairs are removed from specific assets.
```json
{
"event": "AssetMetadataRemove",
"apiKey": "bold-sky-1234",
"entryIds": [
"a1b2c3d4-5678-90ab-cdef-1234567890ab",
"f9e8d7c6-5432-10fe-dcba-0987654321fe"
],
"metadataKeys": ["color", "size"],
"metadataValues": ["red", "large"],
"statuses": [],
"versionIds": []
}
```
#### 9. AssetStatusUpdate
Fired when a status is updated on an asset or a specific asset version. If the status is removed, the "statuses" list will be empty. If the status was set directly on the asset (via the asset dialog "Details" tab), the "versionIds" list will be empty since there is no associated version. However, if the status was set on a specific asset version (via the asset dialog "Versions" tab), the "versionIds" list will contain that version's id.
```json
{
"event": "AssetStatusUpdate",
"apiKey": "bold-sky-1234",
"entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
"metadataKeys": [],
"metadataValues": [],
"statuses": ["In Progress"],
"versionIds": ["1234567890ab"]
}
```
***
