Understand Webhook Event Payloads

When Relayter sends an event to a webhook consumer endpoint, the request body is a JSON CloudEvents-style envelope. Use the event type to route the request and read the changed object from data.

Envelope

{
  "id": "8f8f69fa-5ac6-4be8-92d5-b2d5786ee210",
  "source": "relayter",
  "specversion": "1.0",
  "type": "PRODUCT_UPDATED",
  "data": { "...": "..." }
}

Field	Use
id	Unique event identifier. Use it to make handling idempotent.
source	Identifies the event producer; useful when diagnosing environments.
specversion	Envelope version, currently 1.0.
type	Event name, such as PRODUCT_UPDATED. Use it to select a handler.
data	The changed Relayter object and its related data.

Relayter currently sends CAMPAIGN_CREATED, PRODUCT_UPDATED, ASSET_CREATED, and ASSET_UPDATED events.

PRODUCT_UPDATED payload

For a PRODUCT_UPDATED event, data is the updated product. It includes the product _id and team, plus any linked assets, assetExports, tags, and dataFields. dataFields is a key/value map: its field names and value types depend on the fields configured for your team.

Linked assets

Each item in data.assets represents an asset linked to the product. Common fields include:

• _id, name, and type
• processing, width, height, and rin
• dataFields and groups
• files.source and files.thumbnail

Each available file object contains its own _id, url, urlValidUntil, extension, size, createdAt, and updatedAt.

Product asset exports

Each item in data.assetExports describes a product asset export: name, optional description, format, scaleType, width, height, and items. An item contains its _id and label, a reference to the source asset, and may contain an exportFile with the generated file details.

exportFile uses the same time-limited file-object structure as an asset file.

File URLs expire

files.*.url and exportFile.url are signed URLs. They are valid only until their corresponding urlValidUntil timestamp.

• Process or download a file while its URL is valid.
• Store Relayter _id values as stable references, rather than signed URLs.
• Obtain a fresh URL from Relayter when you need the file again.

Example

{
  "id": "8f8f69fa-5ac6-4be8-92d5-b2d5786ee210",
  "source": "relayter",
  "specversion": "1.0",
  "type": "PRODUCT_UPDATED",
  "data": {
    "_id": "689c581cfc5ed748a9a6798b",
    "team": "5afd3e27ac14d5926d785c7e",
    "dataFields": { "Names": "SPECBOWL!", "Boolean": true },
    "assets": [
      {
        "_id": "665129886be935cd3f9c30dd",
        "name": "00000080024071_C1N1",
        "type": ".tiff",
        "processing": false,
        "width": 2401,
        "height": 2401,
        "files": {
          "source": {
            "url": "https://files.relayter.com/.../original.tiff",
            "urlValidUntil": "2026-02-03T10:12:18Z",
            "extension": ".tiff",
            "size": 4930660
          }
        }
      }
    ],
    "assetExports": [
      {
        "name": "Web image",
        "format": "JPG",
        "scaleType": "BOX_SIZE",
        "width": 1400,
        "height": 1400,
        "items": [
          {
            "label": "Primary",
            "asset": { "_id": "665129896be935cd3f9c30eb", "name": "00000080024873_C1N1" },
            "exportFile": {
              "url": "https://files.relayter.com/.../export.jpg",
              "urlValidUntil": "2026-02-03T10:12:18Z",
              "extension": ".jpg",
              "size": 348380
            }
          }
        ]
      }
    ],
    "tags": []
  }
}

Handle events safely

Return a response promptly and perform expensive processing outside the HTTP request. Build your consumer to ignore fields it does not use and to accept new fields in later payloads. In particular, do not assume that every product has the same dataFields keys or value types.

Related

• Connect a Webhook Consumer to Relayter
• Integrations