Webhooks

Trigger custom API calls from echo3D event triggers.

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.

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 five 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)

---

1. Upload

Fired when a new asset is uploaded to the collection. Only one entryId is ever sent for this trigger.

{
  "event": "Upload",
  "apiKey": "bold-sky-1234",
  "entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
  "metadataKeys": [],
  "metadataValues": []
}

2. Processed

Fired when a new asset is uploaded to the collection and fully processed. Only one entryId is ever sent for this trigger.

{
  "event": "Processed",
  "apiKey": "bold-sky-1234",
  "entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
  "metadataKeys": [],
  "metadataValues": []
}

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.

{
  "event": "Edit",
  "apiKey": "bold-sky-1234",
  "entryIds": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"],
  "metadataKeys": [],
  "metadataValues": []
}

4. Delete

Fired when one or more assets are deleted from the collection. Note that entryIds may contain multiple IDs.

{
  "event": "Delete",
  "apiKey": "bold-sky-1234",
  "entryIds": [
    "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "f9e8d7c6-5432-10fe-dcba-0987654321fe"
  ],
  "metadataKeys": [],
  "metadataValues": []
}

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.

{
  "event": "CollectionMetadataAdd",
  "apiKey": "bold-sky-1234",
  "entryIds": [],
  "metadataKeys": ["category", "environment"],
  "metadataValues": ["furniture", "indoor"]
}

6. CollectionMetadataRemove

Fired when metadata key-value pairs are removed at the collection (project) level.

{
  "event": "CollectionMetadataRemove",
  "apiKey": "bold-sky-1234",
  "entryIds": [],
  "metadataKeys": ["category", "environment"],
  "metadataValues": ["furniture", "indoor"]
}

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.

{
  "event": "AssetMetadataAdd",
  "apiKey": "bold-sky-1234",
  "entryIds": [
    "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "f9e8d7c6-5432-10fe-dcba-0987654321fe"
  ],
  "metadataKeys": ["color", "size"],
  "metadataValues": ["red", "large"]
}

8. AssetMetadataRemove

Fired when metadata key-value pairs are removed from specific assets.

{
  "event": "AssetMetadataRemove",
  "apiKey": "bold-sky-1234",
  "entryIds": [
    "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "f9e8d7c6-5432-10fe-dcba-0987654321fe"
  ],
  "metadataKeys": ["color", "size"],
  "metadataValues": ["red", "large"]
}

---