EventBridge:Event transformation - EventBridge

Event targets often expect a different payload structure than the standard CloudEvents 1.0 format that EventBridge uses internally. Event transformation reshapes the event payload before EventBridge routes it through an event stream to the target, so you can match whatever format the target expects without writing adapter code.

Transformation methods

Four methods control what the target receives:

Method	Behavior	When to use
Complete event	Passes the full CloudEvents payload unchanged	The target accepts CloudEvents directly
Partial event	Extracts specific fields with JSONPath	The target needs only a subset of the event
Constant	Sends a fixed value, ignoring event content	The event is a trigger; its payload is irrelevant
Template	Extracts fields into variables, then composes custom output	The target expects a specific payload structure

All examples on this page use the following sample event as input:

{
    "id": "7adc8c1a-645d-4476-bdef-5d6fb57f****",
    "source": "acs.oss",
    "specversion": "1.0",
    "type": "oss:ObjectCreated:PostObject",
    "datacontenttype": "application/json",
    "dataschema": "http://example.com/test.json",
    "subject": "acs:oss:cn-hangzhou:1234567:xls-papk/game_apk/123.jpg",
    "time": "2020-08-17T16:04:46.149Asia/Shanghai",
    "aliyuneventbusname": "demo-bus",
    "aliyunregionid": "Shanghai",
    "data": {
        "name": "test",
        "scope": 100
    }
}

Complete event

Complete event forwards the entire CloudEvents payload to the target without modification.

Output: Identical to the input. Every field in the CloudEvents envelope and the data payload is preserved.

Partial event

Partial event uses a JSONPath expression to extract specific fields from the CloudEvents payload and delivers only those fields to the target.

JSONPath: $.data

Output:

{
    "name": "test",
    "scope": 100
}

Only the matched content is delivered. The CloudEvents envelope fields (id, source, type, and others) are stripped.

Constant

Constant sends a fixed value to the target regardless of event content. The event serves purely as a trigger.

Constant value:

{
    "name": "test"
}

Output:

{
    "name": "test"
}

Event content is ignored. The constant value is sent as-is.

Template

Template transformation works in two steps:

Extract -- Define variables that pull values from the event with JSONPath or assign fixed strings.
Compose -- Build custom output by referencing those variables with ${variable} syntax.

This method gives full control over the delivered payload.

Variable rules

Constraint	Detail
Value sources	JSONPath expression (e.g., `$.data.name`) or a fixed string
Nesting	Not supported in variable definitions

JSON output with mixed sources

Combine an extracted field with a fixed message:

Variables:

{
    "name": "$.data.name",
    "constant": "Please deal with it timely."
}

Template:

{
    "name": "${name}",
    "constant": "${constant}"
}

Output:

{
    "name": "test",
    "constant": "Please deal with it timely."
}

Plain-text output

Build a notification string from event fields:

For this example, the input event data field contains {"name": "test", "state": "RUNNING"}.

Variables:

{
    "name": "$.data.name",
    "state": "$.data.state"
}

Template:

The ${name} is in ${state} state.

Output:

The test is in RUNNING state.

Escape functions

Variable values that contain special characters can corrupt the output format. Use the built-in escape functions to handle them safely.

jsonEscape

Escapes special characters in JSON strings to prevent malformed output. Use this when embedding variables inside JSON string fields.

Variables:

{
    "var": "\"abc\""
}

Template:

{
    "text": "var is ${jsonEscape(var)}"
}

Output:

{
    "text": "var is \"abc\""
}

htmlEscape

Escapes HTML special characters into their entity equivalents so they render as plain text. Use this to prevent script injection when output contains user-generated content.

Variables:

{
    "var": "<script>alert('unsafe');</script>"
}

Template:

<p>User Input: ${htmlEscape(var)}</p>

Output:

<p>User Input: &lt;script&gt;alert('unsafe');&lt;/script&gt;</p>

Common issues

Issue	Cause	Solution
Variable not replaced in output	The JSONPath expression does not match any field in the event	Verify the JSONPath against the actual event structure. If the path does not match, the variable is not created and appears as a literal `${variable}` string in the output.
Malformed JSON output	Variable value contains special characters (quotes, backslashes)	Wrap the variable reference with `jsonEscape()`. For example, `${jsonEscape(var)}`.
HTML injection in output	Variable value contains HTML tags	Wrap the variable reference with `htmlEscape()`. For example, `${htmlEscape(var)}`.
Template output truncated	Variable value exceeds the maximum length	Shorten the variable value or split the payload into multiple variables.

EventBridge:Event transformation in event streams

Transformation methods

Complete event

Partial event

Constant

Template

Variable rules

JSON output with mixed sources

Plain-text output

Escape functions

jsonEscape

htmlEscape

Common issues

See also