Transformations

A transformation runs your own JavaScript on every event before it's delivered. It can reshape the payload and headers, verify and enrich events, or decode and generate content such as PDFs, archives and images. The runtime is compatible with Node.js and runs npm libraries, so processing you would otherwise deploy as a separate function can run in Hookdeck, as long as it doesn't need network access.

How transformations work

Here are a few common uses:

• 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.
• Verify tokens: For example, decoding a JWT and checking its signature, expiry and audience before delivery
• Work with binary payloads: For example, decompressing a gzip file, extracting data from a PDF, or generating an image

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.

These guides walk through common transformations:

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/2026-09-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

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

curl -X PUT "https://api.hookdeck.com/2026-09-01/connections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-connection",
    "source": {
      "name": "my-source"
    },
    "destination": {
      "name": "my-destination"
    },
    "rules": [
      {
        "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. fetch isn't available, and modules such as fs, http, net and child_process can be imported, but their functions throw.
• Only Node.js built-in modules can be imported. To use npm libraries, bundle them into your code.

Each execution is also bounded by these limits. Async handlers, promises and timers are supported, and time spent awaiting counts toward the execution time.

Large bundles take longer to load the first time they run, roughly 30 ms per MB of code. Minify bundles that include large libraries.

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.

The runtime implements Node.js built-in modules and web APIs inside the isolate, so code written for Node.js runs as long as it doesn't need I/O. In the event that memory or time limits are exceeded, the isolate will terminate the execution of your code.

Your code can use Node.js built-in modules such as crypto and zlib, web globals such as Buffer and URL, async handlers, ES modules, and npm libraries you bundle into it. See Node.js compatibility for the modules, globals and tested npm libraries, how to bundle dependencies, and known gaps.

Transformations syntax

Hookdeck allows for arbitrary transformations on request data using JavaScript (ES6).

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;
});

The handler can be async or return a promise.

Let's take a look at the handler function's component parts.

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 | Buffer | null;
  query: string;
  parsed_query: object;
  path: string;
}

JSON and form payloads arrive as parsed objects, and text payloads as strings.

Binary payloads, such as application/octet-stream, PDFs, images, archives, and requests sent with Content-Encoding: gzip, arrive as a Buffer. Binary bodies larger than 20 MiB arrive as null.

For binary-safe multipart requests, request.body contains parsed text fields and file metadata. Each file also has content, a Buffer holding its bytes, so you can read, replace, add, or remove files. See transform multipart file uploads.

Context object

context is an object containing the connection information. Its structure is denoted below.

{
  connection: Connection;
}

Where Connection is an object, as defined in the response of the GET /connections/:id endpoint.

Return value

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

The parsed_query object in the returned request can safely be ignored – Hookdeck will recreate this parsed query on its own.

The type of the returned body, together with the content-type header, decides what Hookdeck delivers:

Bytes returned with a textual content-type (text/*, JSON, XML, application/x-www-form-urlencoded or application/jwt) become a text payload when they're valid UTF-8, and valid JSON for JSON types. Bytes that don't decode, that declare a charset other than UTF-8, or that are returned with a content-encoding header stay binary.

For a binary request:

• Returning the body unchanged, or null, keeps the original bytes.
• Returning a string or object converts the payload to text. Set a textual content-type with it, such as application/json or text/plain; leaving a binary content type fails the transformation.

For example, this transformation turns a JSON list of orders into CSV:

addHandler('transform', (request) => {
  const rows = request.body.orders.map((order) => `${order.id},${order.total}`);
  request.body = ['id,total', ...rows].join('\n');
  request.headers['content-type'] = 'text/csv';
  return request;
});

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;
  }
}

// Handle that formats the order from Shopify and Woocommerce
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.

Environment variables are managed in the transformations editor via the Variables drop down.

Create a transformation

Transformations are applied to a connection, just like any other rule. But unlike other rules, transformations can be shared between multiple connections.

To version control your transformations, consider creating or updating your connection using the API or the Hookdeck Terraform provider.

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.

   • The left pane's Input tab shows the request your transformation will be tested against. To change this request, click Change and select a recent payload, or edit the text directly.
   • Click Run to test the transformation. Once run, the left pane's Output tab shows the resulting payload, whereas the Diff tab shows the difference between the test input and test output.

6. Name the transformation using the input field in the upper left, clicking Confirm to update the name.

7. Once satisfied with the transformation, click Confirm.

8. Make sure to click Save again on the connection form to apply your changes.

From this point forward, events received on the connection are transformed prior to delivery to their destination.

Edit a transformation

Editing a transformation changes how payload data is transformed before delivery.

1. Open the connection rules configuration.

2. Next to the transformation rule, click Editor.

3. Configure the transformation using the supported transformation syntax in the right-hand pane.

4. Once written, test your transformation.

   • The left pane's Input tab shows the request your transformation will be tested against. To change this request, click Change and select a recent payload, or edit the text directly.
   • Click Run to test the transformation. Once run, the left pane's Output tab shows the resulting payload, whereas the Diff tab shows the difference between the test input and test output.

5. Optionally, you may rename the transformation using the input field in the upper left. Click Confirm to confirm the name change.

6. Once satisfied, click Confirm.

7. 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.

Keep in mind that updating a transformation will affect all connections that use the same transformation. If this is not your desired behavior, you can delete a transformation and create a new one.

Delete a transformation

A Transformation can only be deleted if it is not being used by any Connections.

To remove a transformation from a connection, follow the instructions for configuring connection rules and click the trash icon to remove the transformation from the connection rules.

Once a Transformation has been removed from all Connections, click on Transformations in the sidebar under Connections and select the transformation you wish to delete. Scroll to the bottom of the page and click Delete. Confirm the deletion by clicking Delete in the modal that appears.

Troubleshoot a transformation

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

1. Open the connection rules configuration.

2. Next to the transformation rule, click Editor.

3. Click View Executions.

4. Click an event to open its transformation execution.

   • The Input tab shows the unmodified request received by Hookdeck.
   • The Output tab shows the request after the transformation was applied.
   • The Diff tab shows the difference between the input and output requests.
   • The Console section shows any lines logged to the console in the course of applying the transformation.

Transformation issues

When your transformation fails Hookdeck will log a FATAL execution which will appear in the logs described above. Additionally, a new Issue will be opened. An issue will also be opened if you transformation does execute but logs a warning or an error with console.error or console.warn.

In the case of a fatal failure, Events may have not been created. Hookdeck keeps tracks of those as Ignored Events in the associated issue. Ignored events can be inspected and retried directly within the issue.

1. Open the Issue page.
2. Open the issue of type transformation
3. Inspect the histogram of "Ignored Events" to see the number of events that were not created.
4. Select the latest execution and click "Edit"
5. Make the necessary changes to your transformation code and click "run" to validate that the transformation issue as been resolved.
6. Go back to the original issue, click and submit the "Bulk Retry".

Node.js compatibility

Transformations run in a sandboxed V8 isolate that implements Node.js built-in modules and web APIs, so code written for Node.js runs unchanged as long as it doesn't need I/O. Two rules apply:

• No I/O. Transformations can't reach the network or the filesystem, or start processes. fetch isn't defined.
• Only built-in modules can be imported. To use an npm library, bundle it into your transformation code.

Built-in modules

Import built-in modules with require or import, with or without the node: prefix. require('zlib') and import { gunzipSync } from 'node:zlib' load the same module.

Calling a function from an I/O module fails the transformation with an error like this one:

Error: node:fs.readFileSync is not available in transformations: they run without filesystem, network or process access.

Pure helpers and constants on those modules still work, such as net.isIP and http.METHODS, and you can construct an http.Agent.

Globals

These globals are available without an import:

• Buffer, TextEncoder, TextDecoder, atob, btoa
• URL, URLSearchParams
• crypto (WebCrypto, including crypto.subtle and crypto.randomUUID)
• structuredClone, queueMicrotask
• AbortController, AbortSignal, Event, EventTarget, CustomEvent, DOMException
• Blob, File, Headers, FormData, navigator, performance
• Web streams: ReadableStream, WritableStream, TransformStream, TextEncoderStream, TextDecoderStream, CompressionStream, DecompressionStream
• setTimeout, setInterval, setImmediate and their clear* functions
• process, with process.env holding your environment variables
• WebAssembly

fetch, WebSocket, MessageChannel and BroadcastChannel aren't available.

Dynamic import() of a built-in module works, for example await import('node:crypto').

Script and module formats

A transformation can be a classic script that registers its handler with addHandler:

const { createHmac } = require('node:crypto');

addHandler('transform', async (request, context) => {
  request.headers['x-signature'] = createHmac('sha256', process.env.SIGNING_SECRET)
    .update(JSON.stringify(request.body))
    .digest('hex');
  return request;
});

Code with a top-level import or export runs as an ES module. Export the handler as export default { transform }, as a default function, or as a named transform function:

import { createHash } from 'node:crypto';

export default {
  transform(request, context) {
    request.headers['x-body-sha256'] = createHash('sha256')
      .update(JSON.stringify(request.body))
      .digest('hex');
    return request;
  },
};

Modules support top-level await, and import.meta.url is defined.

Async code and timers

Handlers can be async or return a promise. Timers and node:timers/promises work.

The whole execution is limited to 1 second, including time spent awaiting promises and timers. A transformation that runs longer fails with Script execution timed out.

Bundle dependencies

Transformations can't install packages. To use an npm library, bundle it and its dependencies into a single file with esbuild, then use the bundle as your transformation code.

1. Install the library and esbuild:

   npm install fast-xml-parser
   npm install --save-dev esbuild
   

2. Write the transformation as an ES module that imports the library:

   import { XMLParser } from 'fast-xml-parser';
   
   const parser = new XMLParser({ ignoreAttributes: false });
   
   export default {
     transform(request) {
       request.body = parser.parse(request.body);
       request.headers['content-type'] = 'application/json';
       return request;
     },
   };
   

3. Bundle it:

   npx esbuild transform.js --bundle --format=esm --platform=node --outfile=dist/transform.js
   

   --platform=node leaves imports of Node.js built-ins in place, so the bundle uses the runtime's built-in modules. Add --minify to make the bundle smaller.

4. Paste the contents of dist/transform.js into the transformation editor, or upload the file with the Hookdeck CLI:

   hookdeck gateway transformation upsert xml-to-json --code-file dist/transform.js
   

If you prefer an addHandler script, require the library and bundle with --format=cjs instead:

const { XMLParser } = require('fast-xml-parser');

const parser = new XMLParser({ ignoreAttributes: false });

addHandler('transform', (request) => {
  request.body = parser.parse(request.body);
  request.headers['content-type'] = 'application/json';
  return request;
});

npx esbuild transform.js --bundle --format=cjs --platform=node --outfile=dist/transform.js

Importing an npm package without bundling it fails with:

Error: Cannot find module 'lodash'. Only Node.js built-in modules (e.g. 'node:crypto') can be required in a transformation; bundle other dependencies into your code.

When a library offers both a synchronous and an asynchronous API, prefer the synchronous one. It's simpler to reason about within the 1-second limit, and some asynchronous APIs rely on worker threads, which aren't available.

npm library compatibility

Hookdeck tests popular I/O-free npm libraries against the transformation runtime. Each library is bundled with esbuild the way you would bundle it, both as an ES module (ESM, --format=esm) and as an addHandler script (CJS, --format=cjs). The bundle then runs in the transformation runtime and in Node.js, and the test passes only if both produce exactly the same output.

60 of the 61 library cases pass. A library that isn't listed may still work: if it doesn't need I/O, bundle it and test it in the transformation editor.

Auth and crypto

XML, CSV and text formats

Binary encodings and compression

Validation

Dates

Data manipulation and querying

Node.js built-in tests

The built-in modules are tested the same way as the libraries, by comparing the runtime's output with Node.js. All 21 groups pass.

Known gaps