Transformations and Payload Shaping

PayloadRelay can change the incoming payload before the delivery. A transform rule applies to each accepted request, after the field validation and before the delivery. The formatting for each destination then adapts the changed payload.

Purpose#

Use this guide to:

• Mask a sensitive field, such as a credit card number and an email address, before the delivery.
• Replace a field value with fixed data or calculated data.
• Remove a field that the delivery must not contain.
• Change a field type, such as a string to a number, or a string to a boolean.
• Apply a regular expression substitution to a payload.
• Add fields from the request metadata.
• Configure the formatting and the field selection for an email, Slack, Discord, Microsoft Teams, Telegram, and Google Sheets target.

Before you start#

• Make sure that you can edit the endpoint.
• Attach one relay target as a minimum.

Transform rules#

A transform rule changes the payload on the endpoint. Every destination receives the changed version. PayloadRelay applies the rules in order. To change the order, use the up control and the down control.

Field selector syntax#

Each rule uses a selector expression to identify a specific field:

A selector has a maximum of 200 characters. PayloadRelay ignores a missing field and a missing intermediate path, and it does not reject the request.

Rule types#

Replace a field value with mask characters. You can change the mask length.

maskChar is * by default. If you give a value, it must be exactly one non-control character. With the randomize length control enabled, the mask is 1 to 8 characters. If the control is disabled, the mask length is the same as the string form of the field. The length information thus stays.

Example: mask a credit card number.

Field:    cardNumber
Type:     MASK
Char:     *
Result:   "****-****-****-1234" (last 4 preserved by using REPLACE on other rules)

REPLACE: replace field values

Replace the current value of a field with a new value.

For a JSON, form, or query payload, a NUMBER replacement must parse as a number. A BOOLEAN replacement must be true or false. PayloadRelay rejects an invalid value when you save the endpoint. NULL sets the field to JSON null, and it does not delete the field.

Examples:

• Replace an environment tag: set env to production (type: TEXT).
• Set a numeric field: set priority to 1 (type: NUMBER).
• Set a field to null: set debugInfo to null (type: NULL).

Remove a field from the payload. The field does not appear in a delivery. For an array, a numeric selector such as items.1 removes that array element, and it moves the later entries to the left.

Example: remove internal metadata before forwarding.

Field:   _internalRequestId
Type:    DELETE

TYPE_CAST: change the data type

Change a field value to a different JSON type. Use this rule when the sender sends strings and the receiver needs typed values.

Examples:

• Cast to NUMBER: "42" (string) becomes 42 (number).
• Cast to BOOLEAN: "true" (string) becomes true (boolean).
• Cast to TEXT: "hello" (string) stays "hello" (string, with no change).

If PayloadRelay cannot parse the value as the target type, for example, "abc" cast to NUMBER, it sets the field to null. TYPE_CAST is not available for an XML payload or a plain-text payload.

Apply a regular expression find-and-replace operation to a text value of a field. A pattern uses the Java-compatible syntax. PayloadRelay examines a pattern when you save it. At the delivery, the replacements apply to all the matches, with multiline behavior and dot-matches-newline behavior, the $1 and $2 group references, and a 1-second safety timeout. If a replacement fails or times out, PayloadRelay keeps the original value.

Example: normalize phone numbers by removing non-digit characters.

Field:       phoneNumber
Pattern:     [^0-9]
Replacement: (empty)
Result:      "+15551234567" → "15551234567"

Append fields#

An append field adds endpoint data after the transform rules apply. Every destination receives the payload with the added fields. The added fields are available to a webhook body, the routing, the outbound HMAC signing, Google Sheets, the email formatting, and the message templates.

Behavior and limits:

• An endpoint can have a maximum of 20 append rules.
• A field name has a maximum of 200 characters. A value has a maximum of 65,536 characters.
• A JSON, form, and query payload needs a valid dot path. PayloadRelay rejects a duplicate append field name. An append rule writes over an existing field at that path.
• NUMBER supports an integer, a decimal, and scientific notation. PayloadRelay rejects an invalid number when you save. BOOLEAN must be true or false. NULL writes an actual JSON null, and it ignores the value field.
• An XML append rule adds a child element to the root element. It adds raw text when the element name is blank. A plain-text rule adds the literal value to the end of the body.
• A None payload and a bodyless GET or HEAD endpoint clear the append rules. A query-parameter format can use the append rules, because it makes a JSON payload.
• A JSON array root and a JSON scalar root cannot receive appended fields. To append structured fields, use a JSON object payload.

Per-output formatting#

After the transforms apply, each destination formats the payload for its destination type. Configure these values for each destination in the Outputs tab.

Email outputs#

For RAW_PAYLOAD_ROWS, an XML payload uses its own structure. A text/plain payload stays raw text.

Slack outputs#

• The Markdown control: when it is enabled, the Slack mrkdwn formatting (*bold*, _italic_, <url|text>) applies to the Slack text that PayloadRelay creates, and to the body sections of a message template. Slack-native blocks or attachments from the sender keep their own formatting rules.

Discord outputs#

• The TTS (Text-to-Speech) control: when it is enabled, Discord speaks the messages. Use it for an urgent alert.
• The control that cuts a long message: it is disabled by default. When it is disabled, Activity records Discord content above the Discord 2000-character limit as a failed delivery. When it is enabled, PayloadRelay makes the content shorter before it sends the message.

Transform order and behavior#

1. The request arrives and passes the inbound authentication, the rate limits, the body filters, the captcha test, and the field validation.
2. PayloadRelay removes the captcha fields that the configuration excludes.
3. PayloadRelay applies the transform rules in the configured order, from the top to the bottom. A later rule uses the earlier results.
4. The append field rules apply after the transforms. They can write over a field that an earlier rule changed or removed.
5. PayloadRelay uses the payload with the transforms and the appended fields for the routing, the outbound HMAC signing, the formatting for each destination, and the delivery.
6. Each destination applies its own formatting, such as an email body or the Slack Markdown.

An accepted activity log does not store a request body, original or transformed. A delivery attempt uses the transformed payload. When the transforms are configured, PayloadRelay does not send the original raw body for a failover.

The transforms change the payload one time, on the endpoint. The values for each destination only format the result. They cannot change the individual fields again. For destination-specific content, use message templates on a Slack, Discord, Teams, or Telegram destination. You can also use routing filters for different destinations.

Expected result#

• PayloadRelay masks or removes a sensitive field before the delivery.
• The field types agree with the downstream systems.
• An email message uses the selected body format.
• A Slack message and a Discord message obey the Markdown control, the TTS control, and the Discord cut control.

Common issues and fixes#

• PayloadRelay does not apply the transform: make sure that the field selector is correct. A JSON path uses the dot notation (user.email, items.0.name), XML uses XPath, and text/plain uses $ or a plain substring match.
• A CAST to NUMBER fails with no message: a value that is not a number, such as "abc", becomes null. If you need a fallback value, use a REPLACE rule.
• The email body is wrong: change the body format (RAW_PAYLOAD, or TEXT with a template), and read the preview before you save.
• The Slack formatting fails: turn on Markdown for the destination, and use the Slack mrkdwn syntax, not the standard Markdown.
• The regex group references fail: use the Java syntax $1 and $2, and not the Python syntax \1 and \2.

Related guides#

• Endpoint Management
• HTTP Methods and Payload Formats
• Routing Filters: send different payloads to different targets.
• Message Templates: format a Slack, Discord, Teams, and Telegram message.
• Observability
• Troubleshooting