Payload transformation

What can a transformation do?

A transformation runs after receipt and before delivery. It can rename fields, drop fields, flatten nesting, add a constant, or emit an entirely different shape. The stored original is never modified, so replay after removing the transformation sends the provider’s bytes untouched.

Why use one?

• Strip personal data you do not want stored downstream or forwarded to a third party.
• Adapt a provider’s shape to the one your handler already expects, instead of writing an adapter.
• Add routing fields your own systems use, such as a tenant id derived from the payload.

What does one look like?

Transformations are expressions over the parsed body, evaluated in a sandbox with no network and no clock access.

{
  "id": "$.data.object.id",
  "amount": "$.data.object.amount_total",
  "currency": "$.data.object.currency",
  "customer_email": null,
  "source": "stripe"
}

Mapping a field to null removes it. Anything not mentioned is dropped, so the output is explicit rather than a filtered copy.

What happens if a transformation fails?

The event is delivered untransformed and the attempt is marked with the transformation error. Delivery never blocks on a transformation problem, because a failed reshape is less bad than a missed event.

Does the signature still verify?

The ShellOrbit signature is computed over the body that is actually sent, so it verifies against the transformed body. The provider’s own signature will not verify against a transformed body, which is expected. Verify the provider signature at ingest instead, as described in signature verification.

How do I test one?

Run it against any stored event from the dashboard. You see the input, the output, and the diff before it is applied to live traffic.