Transformations

HookDeploy’s payload transformation editor lets you modify webhook payloads before they reach each forward destination. No code, no JSONata — configure rules in the dashboard and preview against a captured request.

Configure transformations per destination in Endpoint → Settings → Forward destinations → Configure transform.

To reshape what HookDeploy stores (without changing what destinations receive), see Privacy filters.

Transformation modes

When to use passthrough

Your webhook sender sends a rich payload and you only need to rename amount to amount_usd, mask an email, or add a source field. Most fields pass through untouched.

When to use allowlist

You’re forwarding to a third-party analytics tool and want to send only event_type and amount — nothing else. Allowlist mode ensures no accidental PII leakage.

Field path syntax

Paths use dot notation to reach nested fields:

amount                    → top-level field
data.amount               → nested object
customer.email            → deeply nested
items.0.price             → first array element's price field

When you add a field rule, the output path defaults to the full source path (for example data.amount → data.amount). Change Rename to only when you want a different key. Nested allowlist selections keep their nested structure in the output.

In the visual editor, click any field in the JSON tree to add a transform rule. The editor loads your latest captured webhook as sample data so you can preview changes live.

Supported body formats

Transformations run on:

• JSON bodies (application/json and JSON-parsed payloads)
• Form-encoded bodies (application/x-www-form-urlencoded)

Form fields are parsed with standard URL form rules: a key that appears once stays a string; a key that appears more than once becomes an array.

a=1&b=2&b=3  →  { "a": "1", "b": ["2", "3"] }

Other content types are not transformed; the original body is forwarded unchanged.

Per-destination output format

Each forward destination has an output format:

If you choose Keep original format but the transformed object has nested objects (or other values form encoding cannot represent), HookDeploy falls back to JSON and records an error on the forward result. The transformed data is still delivered — it is not discarded.

Source × output matrix

Conditions

Any field or combine rule can include an Only when… condition. If the condition fails and you have not configured Otherwise… formatters, the rule is skipped (no write to the target path). If Otherwise… is configured, those formatters run instead.

Condition fields

Operators

Type coercion

These rules matter when your condition value is typed differently from the payload field:

• equals / not_equals: Same-type values use strict equality. A number and a numeric string can match (42 equals "42"). A boolean can match the lowercase strings "true" / "false". Other mixed types do not match via string conversion — for example 42 does not equal "42px", and an object never equals a string.
• greater_than / less_than: Both sides run through Number(). If either side is NaN, the comparison fails (does not pass).
• contains: Arrays use the same equality rules as equals for each element. Non-string, non-array left values fail.

Combine rules

Use Combine fields to join multiple source paths into one output string, then optionally run formatters and conditions on the result.

Missing sources contribute an empty segment and a warning in the transform result.

Error handling

Formatters run independently per rule. If a formatter fails, that rule keeps the value from before the failed formatter and continues with remaining formatters when applicable. Other rules still apply. Errors are listed on the forward result — the destination still receives the partially transformed payload (not the pre-transform original, unless the transform never ran).

Storage privacy filters behave differently: see Privacy filters.

Formatter reference

Formatters run in the order you add them. Chain multiple formatters on one field — for example, cents_to_currency then prefix with value "USD ".

There are 35 built-in formatters. Two older aliases (cents_to_dollars, dollars_to_cents) still run on existing configs but are superseded by the currency formatters below.

Numeric

Zero-decimal currencies (for example JPY) and three-decimal currencies (for example KWD) use the engine’s ISO minor-unit rules.

String

Date / time

format_date tokens (UTC): YYYY MM DD HH mm ss SSS. Example pattern: YYYY-MM-DD HH:mm:ss.

Numeric timestamps smaller than 1e12 are treated as Unix seconds; larger values as milliseconds.

Type conversion

Value override

Limits

These bounds are enforced when you save a transformation and again when it runs:

Static fields

Add key-value pairs that appear in every forwarded payload regardless of the source webhook. Useful for injecting tenant IDs, source labels, or schema version markers:

{
  "source": "hookdeploy",
  "tenant_id": "acme-corp"
}

Static fields appear in the live preview in green. They are merged into the transformed output after field rules are applied.

Common recipes

Strip PII before forwarding to analytics

Mode: Passthrough

1. Load a sample webhook in the transform editor
2. Click customer.email in the field tree
3. Enable Strip field (PII) on the rule card
4. Repeat for customer.phone, customer.name, etc.
5. Save the transform

Your analytics destination receives the full event minus sensitive customer fields.

Convert Stripe amounts with currency

Mode: Passthrough

1. Click data.object.amount (or your amount field path)
2. Optionally rename the output path
3. Add formatter: cents_to_currency with currency USD
4. Preview shows "42.00" from input 4200

See also: Stripe webhooks.

Normalize timestamp formats

Mode: Passthrough

1. Click your Unix timestamp field (e.g. created)
2. Add formatter: unix_to_iso
3. Output becomes ISO 8601 with milliseconds: "2024-05-28T14:01:00.000Z"

For date-only fields, use unix_to_date. For custom layouts, use format_date.

Mask an email only in live mode

Mode: Passthrough

1. Add a rule on customer.email with formatter mask
2. Open Only when…
3. Path: livemode, operator: equals, value: true
4. Without Otherwise…, test-mode emails pass through unchanged

Allowlist only the fields your server needs

Mode: Allowlist

1. Switch mode to Allowlist
2. Select the nested paths your server expects — for example event_type, data.id, data.amount
3. Add formatters as needed (e.g. cents_to_currency on data.amount)
4. Preview confirms selected fields keep their nested paths unless you rename them

Everything else — including unexpected PII — is dropped.

Transform Twilio or Slack form posts

1. Capture a form-urlencoded webhook (Twilio, Slack slash commands, etc.)
2. Configure the destination transform against the parsed fields
3. Prefer JSON output unless the downstream still requires form encoding
4. If you need form output, keep the transform flat (no nested objects)

Live preview

The editor runs your transformation against sample data in real time:

• Unchanged fields — default text color
• Transformed fields — orange/warning color
• Static fields — green/success color
• Removed fields — shown as comments in passthrough mode
• Hash — preview shows a clear placeholder; the real SHA-256 runs at forward time

Load your latest captured request or paste custom JSON to test against Stripe, GitHub, Twilio, or any provider payload. Preview errors mirror production forwarding: failed formatters keep their input value and other rules still apply.

Plan availability

Payload transformation for forwarding is available on Starter and above. Forwarding transformations are not limited by formatter type — every formatter listed here is available once transformations are unlocked.

Privacy filters (storage) use a different plan gate. See Privacy filters.

Next steps

• Privacy filters — Redact or reshape what HookDeploy stores
• Forwarding — Multiple destinations and header injection
• Stripe webhooks — Stripe-specific transformation example
• REST API — Manage destinations programmatically