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

# Metadata and correlation

> Put ownership, routing context and business correlation in the right place without turning metadata into a hidden control plane.

Metadata is a small JSON object attached to a definition or occurrence. Use it to find related work, record ownership and supply explicit routing context. It is not secret storage, a permission grant or automatic duplicate protection.

## Choose the right object

| Location | Useful content | What consumes it |
| - | - | - |
| Component, Event or Job-template definition metadata | Owner, environment, managed integration, portable `stableKey` | Discovery, administration and explicitly configured tools such as CLI identity matching |
| Published Event metadata | `correlationId`, `operationKey`, `source` | Event history, API filters over `metadata.*`, and the target's `api.input('metadata')` |
| Event message | Business IDs and the fields subscribers inspect | Filters over `message.*`; the target's `api.input('message')` |
| A resource's metadata inside an Event message | For example, the Storage entry's `pipeline` label | `message.metadata.pipeline`, a different path from occurrence metadata |
| Webhook metadata | Originating Event, Job or operation references | RevoEngine history and search; not automatically the outbound HTTP body or headers |

For `ORDER_APPROVED`, use definition metadata to find the checkout subscription, occurrence metadata to trace one approval, and the message to carry `orderId`. Set the Job's execution configuration in Runtime input.

```mermaid theme={null}
flowchart TD
  A["Published Event occurrence"] --> B["message.orderId · business input"]
  A --> C["metadata.correlationId · occurrence context"]
  D["Job template and Event Runtime input"] --> E["templateInputs · execution configuration"]
  B --> F["Selected Job"]
  C --> F
  E --> F
```

Definition metadata stays with the definition. When the Job creates a Webhook, choose which values to include in its own metadata and which to send in the request.

## Publish a traceable signal

Run this fragment in a low-code Component after establishing that the order was approved. Register an active custom `ORDER_APPROVED` Event targeting the intended Job template first.

```js theme={null}
const eventId = await api.triggerEvent(
  'ORDER_APPROVED',
  { orderId: 'order-1', region: 'eu', total: 12500 },
  {
    metadata: {
      correlationId: 'checkout-1',
      operationKey: 'order-1:invoice:v1',
      source: 'checkout',
    },
  },
);
return { accepted: true, eventId };
```

The returned ID confirms durable Event acceptance, not invoice completion. In the target Component, read `api.input('message')` and `api.input('metadata')`. Validate their contents, load the authoritative order and deliberately carry the operation key into the receiver contract or business record.

For a later Webhook, set its own `metadata` explicitly if you want the same correlation values in Webhook history. Set `request.body` or a receiver-supported header separately when the partner needs that identity. Metadata is not silently forwarded between every product boundary.

## Filter in the correct namespace

An API Event filter can select the occurrence's source:

```json theme={null}
{ "field": "metadata.source", "op": "eq", "value": "checkout" }
```

The visual Event filter editor accepts **message-relative** fields. Entering `metadata.pipeline` there selects `message.metadata.pipeline`, not the occurrence's top-level metadata. Use the API for a filter on top-level `metadata.source`. Explore this distinction in [Event filters](https://docs.revoengine.com/operate/event-filters.md#explore-the-behavior).

When searching history, use the structured filter supported by that list operation. Database row filters, Event subscription filters and Platform API history filters are separate contracts; do not copy one query shape into another surface unchanged.

## Keep correlation and protection separate

A `correlationId` groups related activity, such as all steps in checkout. An `operationKey` identifies one business effect, such as issuing one invoice. A resource ID identifies a stored object. They can appear together, but serve different purposes.

Setting `metadata.operationKey` does not call `api.acquireIdempotencyKey()` or make an external service idempotent. Use the [idempotency pattern](https://docs.revoengine.com/patterns/idempotency.md) and retain the durable result. A new Event history ID on Replay should not accidentally create a new business identity.

## Limits and handling

Standard user metadata accepts JSON values and is bounded to **16 KiB of UTF-8 JSON** and **64 top-level keys**. Top-level names beginning with `__` are reserved. Use a small consistent schema; avoid changing a numeric field to a string across producers.

Store large payloads in Storage or Tables and carry their IDs. Keep credentials, raw authorization headers and sensitive personal data out of metadata, which is designed for discovery and operational inspection. Update behavior belongs to the resource's API contract; do not assume that a partial metadata object performs a deep merge.

Continue with [Event input](https://docs.revoengine.com/operate/event-inputs.md), [delivery guarantees](https://docs.revoengine.com/patterns/delivery-guarantees.md) and [Trace](https://docs.revoengine.com/operate/traces.md).

Follow the complete [Event → Job → Webhook example](https://docs.revoengine.com/patterns/event-to-webhook.md) to connect configuration, inputs, correlation and observable outcomes.


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