Transformations

A transformation lets you modify the payload of an event prior to delivery.

How transformations work

You can use transformations to solve many problems. Here are a few common scenarios:

• Change payload formats: For example, converting XML to JSON
• Unify models across sources: For example, conforming WooCommerce orders and Shopify orders to a single standard
• Add compatibility when routing to an API: For example, adding keys and reformatting the payload
• Add additional properties to payloads: For example, to more clearly indicate the event type for use in a filter or in your own application logic.

Transformations and filters can be executed in any order. You can configure the execution order by dragging them in the UI or ordering them in the rules[] array in the API.

Add a transformation via the API

You can create a transformation and add it to a connection programmatically. This is a two-step process: first create the transformation, then add it as a rule on a connection.

Step 1: Create the transformation

curl -X POST "https://api.hookdeck.com/2025-07-01/transformations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "add-event-type-header",
    "code": "addHandler(\"transform\", (request, context) => { request.headers[\"x-event-type\"] = request.body.type; return request; });"
  }'

Step 2: Add the transformation rule to a connection

hookdeck connection upsert my-connection \
  --rules-file rules.json

Where rules.json contains:

[
  {
    "type": "transformation",
    "transformation_id": "trs_123456789"
  }
]

Syntax

Hookdeck allows for arbitrary transformations on request data using JavaScript (ES6). For a complete overview, see transformations syntax.

Limitations

Transformations have some important limitations to keep in mind.

• The transformation runtime cannot perform any IO, or access any external resources such as the network or file system.
• The transformation runtime does not support promises and async/await.
• The execution runtime is limited to 1 second.
• Transformation code is limited to 5 MB.
• Transformations run in environments known as isolates, which carry their own set of limitations.

Environment

Hookdeck sandboxes your transformation process within a V8 runtime environment known as an isolate. Isolates allow multiple JavaScript VM instances to operate in parallel, sharing low-level resources while remaining fundamentally distinct and secure.

Supported methods

The following methods are supported out of the box.

• JSON.parse
• JSON.stringify

Handler function

The transformation handler is used to apply changes to a request. For example, the transformation code below adds a new header to the payload.

addHandler("transform", (request, context) => {
  request.headers["example-header"] = "Hello World";
  return request;
});

Request object

request is the request object received on the connection. Its structure is denoted below.

{
  "headers": { "[key: string]": "string" },
  "body": "string | boolean | number | object | null",
  "query": "string",
  "parsed_query": "object",
  "path": "string"
}

Return value

The handler must return a valid request object, containing a valid content-type header.

The following transformation formats an order based on its source:

const formatOrder = (order, type) => {
  if (type === 'shopify') {
    // Format for shopify here
    return order;
  } if (type === 'woocommerce') {
    // Format for woocomerce here
    return order;
  }
};

addHandler('transform', (request, context) => {
  const { body, headers, path, query } = request;
  const { connection } = context;
  return {
    body: formatOrder(body, connection.source.name),
    headers,
    path,
    query
  };
});

Environment variables

Transformations support environment variables for storing secrets. Access your variable on the process.env object. For example, to access a variable called TEST use process.env.TEST.

Create a transformation

Transformations are applied to a connection, just like any other rule.

1. Open the connection rules configuration.
2. Click Transform to add a transformation rule.
3. Click Create new transformation.
4. Configure the transformation using the supported transformation syntax in the right-hand pane.
5. Once written, test your transformation.
6. Name the transformation using the input field in the upper left, clicking Confirm to update the name.
7. Once satisfied, click Confirm.
8. Make sure to click Save again on the connection form to apply your changes.

Transformations are updated immediately, and any events received going forward are run through the updated transformation.

Troubleshoot a transformation

Execution logs are kept for every transformation, in order to facilitate troubleshooting.