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.

What transformations are used for

Across the transformations running in Hookdeck projects, the most common job is changing headers, followed by reshaping the payload into the format a destination's API expects. Common uses include:

• Add, remove and rewrite headers: For example, adding an API key or Authorization header, adding a header that names the event type, or removing headers the destination shouldn't receive. For a static API key, bearer token or basic auth, destination authentication does this without code. Use a transformation when the credential is derived from the request or the destination expects it somewhere else.
• Sign or encrypt outgoing requests: For example, computing an HMAC of the body with node:crypto when the destination verifies requests with its own signature scheme, or encrypting a payload before delivery
• Post to chat tools: For example, turning a Stripe, GitHub or Shopify event into a Slack, Discord, Microsoft Teams or Telegram message
• Send notifications: For example, mapping an event to the request body Knock, SendGrid or Twilio expects, to send an in-app notification, email or SMS
• Trigger background jobs: For example, wrapping the payload in an Inngest event's name and data, or in the payload of a Trigger.dev task, and setting the request path to the endpoint for that job
• Unify models across sources: For example, conforming WooCommerce orders and Shopify orders to a single standard
• Remove fields: For example, dropping fields a destination rejects, or stripping personal data before an event leaves your stack
• Change payload formats: For example, converting XML to JSON, decoding MessagePack or protobuf into JSON, or turning a JSON payload into CSV or YAML
• 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 and files: For example, decompressing a gzip or zip file, extracting data from a PDF, editing the files in a multipart upload, or generating an image

This transformation posts a Stripe event to a Slack incoming webhook:

addHandler('transform', (request) => {
  const { type, data } = request.body;
  request.body = { text: `Stripe event \`${type}\` for ${data.object.id}` };
  return request;
});

These guides walk through common transformations:

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. An execution that exceeds the time or memory limit is terminated.

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

Transformations syntax

Transformations are written in JavaScript, as a classic script or as an ES module, and can import Node.js built-in modules.

Handler function

The transformation handler is used to apply changes to a request. For example, both versions of the transformation code below add a header containing a SHA-256 hash of the body.

A classic script registers its handler with addHandler, and imports modules with require:

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

addHandler('transform', (request, context) => {
  request.headers['x-body-sha256'] = createHash('sha256')
    .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.

The handler can be async or return a promise. See async code and timers for the execution time limit.

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

hookdeck gateway transformation upsert add-event-type-header \
  --code-file transform.js \
  --env TEST=value

{
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "env": {
    "FOO": "BAR"
  }
}

{
  "id": "trs_3g5n4Sl0pCxcqc",
  "team_id": "tm_lbhzBKgFOUnB",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2026-01-14T13:36:42.402Z",
  "created_at": "2026-01-14T13:35:55.281Z",
  "code_hash": "d0b47e9e392b05d7357ab1cab511f03648bf53cb",
  "deleted_at": null,
  "env": {
    "FOO": "BAR"
  }
}

{
  "name": "add-event-type-header",
  "code": "addHandler('transform', (request, context) => request);",
  "env": {
    "TEST": "value"
  }
}

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.

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.

To version control your transformations, consider creating them and updating your connections using the CLI, the API or the Hookdeck Terraform provider.

hookdeck gateway connection upsert my-connection \
  --rule-transform-name add-event-type-header \
  --rule-transform-code "$(cat transform.js)"

{
  "request": {
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "example": true
    },
    "path": "/",
    "query": "",
    "parsed_query": {}
  },
  "code": "addHandler('transform', (request, context) => request);"
}

{
  "log_level": "info",
  "console": [],
  "request": {
    "headers": {
      "content-type": "application/json",
      "content-length": "16"
    },
    "body": {
      "example": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  },
  "transformation_run_time": {
    "start": 1768397802428,
    "end": 1768397802433
  }
}

curl -X PUT "https://api.hookdeck.com/2026-09-01/transformations/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "addHandler(\"transform\", (request, context) => { request.headers[\"x-event-type\"] = request.body.type; return request; });",
    "request": {
      "headers": { "content-type": "application/json" },
      "body": { "type": "order.created" }
    }
  }'

{
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "env": {
    "FOO": "BAR"
  }
}

{
  "id": "trs_3g5n4Sl0pCxcqc",
  "team_id": "tm_lbhzBKgFOUnB",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2026-01-14T13:36:42.402Z",
  "created_at": "2026-01-14T13:35:55.281Z",
  "code_hash": "d0b47e9e392b05d7357ab1cab511f03648bf53cb",
  "deleted_at": null,
  "env": {
    "FOO": "BAR"
  }
}

curl -X PUT "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; });"
  }'

{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "config": {
      "url": "https://mock.hookdeck.com/example"
    }
  }
}

{
  "id": "web_nbbweTiOtzsm",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.634Z",
  "created_at": "2026-01-14T13:36:41.595Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "rules": [],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "delivery_policy": {
        "rate": null,
        "period": "second",
        "groups": null
      },
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-my-api"
}

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": "transform",
        "transformation_id": "trs_123456789"
      }
    ]
  }'

{
  "type": "transform",
  "transformation": {
    "name": "add-event-type-header",
    "code": "addHandler(\"transform\", (request, context) => { request.headers[\"x-event-type\"] = request.body.type; return request; });"
  }
}

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.

{
  "request": {
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "example": true
    },
    "path": "/",
    "query": "",
    "parsed_query": {}
  },
  "code": "addHandler('transform', (request, context) => request);"
}

{
  "log_level": "info",
  "console": [],
  "request": {
    "headers": {
      "content-type": "application/json",
      "content-length": "16"
    },
    "body": {
      "example": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  },
  "transformation_run_time": {
    "start": 1768397802428,
    "end": 1768397802433
  }
}

{
  "code": "addHandler('transform', (request, context) => request);"
}

{
  "id": "trs_3g5n4Sl0pCxcqc",
  "team_id": "tm_lbhzBKgFOUnB",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2026-01-14T13:36:42.416Z",
  "created_at": "2026-01-14T13:35:55.281Z",
  "code_hash": "65712742f42111c4f71c59d74fa37aac858389e7",
  "deleted_at": null,
  "env": {
    "FOO": "BAR"
  }
}

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

Keep in mind that updating a transformation affects every connection that uses it. To change the behavior for one connection only, create a new transformation and replace the transformation rule on that connection with it.

Delete a transformation

A transformation can only be deleted if it is not being used by any connections, so remove it from each connection's rules first.

{
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear"
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ]
}

{
  "id": "web_FMKlTwAoGFRu",
  "team_id": "tm_lbhzBKgFOUnB",
  "updated_at": "2026-01-14T13:36:41.659Z",
  "created_at": "2026-01-14T13:36:06.347Z",
  "paused_at": null,
  "name": "shopify-orders",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear",
      "response_status_codes": null
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "description": null,
  "destination": {
    "id": "des_TU9ioCk5EHUU",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.263Z",
    "name": "my-api",
    "description": null,
    "type": "HTTP",
    "config": {
      "url": "https://mock.hookdeck.com/example",
      "delivery_policy": {
        "rate": null,
        "period": "second",
        "groups": null
      },
      "http_method": null,
      "path_forwarding_disabled": false,
      "auth": {},
      "auth_type": "HOOKDECK_SIGNATURE"
    },
    "disabled_at": null
  },
  "source": {
    "id": "src_qa5626p6y5o79b",
    "team_id": "tm_lbhzBKgFOUnB",
    "updated_at": "2026-01-14T13:36:41.615Z",
    "created_at": "2026-01-14T13:35:55.226Z",
    "name": "shopify",
    "description": null,
    "type": "WEBHOOK",
    "config": {
      "allowed_http_methods": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "custom_response": null
    },
    "url": "http://localhost:8787/qa5626p6y5o79b",
    "disabled_at": null,
    "authenticated": false
  },
  "disabled_at": null,
  "full_name": "shopify -> shopify-orders"
}

{
  "id": "trs_3g5n4Sl0pCxcqc"
}

Troubleshoot a transformation

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

hookdeck gateway transformation executions list add-event-type-header

{
  "pagination": {
    "order_by": "ingested_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "reqt_WlhldMqr9R5ZEgVTd3",
      "team_id": "tm_lbhzBKgFOUnB",
      "created_at": "2026-01-14T13:36:36.022428Z",
      "updated_at": "2026-01-14T13:36:36.022428Z",
      "webhook_id": "web_u05hx7tvkvd8",
      "transformed_event_data_id": "edt_WlhldMqr9R5ZEgVTd3aC",
      "original_event_data_id": "edt_v5FblvaIn2WWrmEKbGvU",
      "transformation_id": "trs_3g5n4Sl0pCxcqc",
      "log_level": "info",
      "logs": []
    }
  ]
}

{
  "id": "reqt_WlhldMqr9R5ZEgVTd3",
  "original_event_data_id": "edt_v5FblvaIn2WWrmEKbGvU",
  "transformed_event_data_id": "edt_WlhldMqr9R5ZEgVTd3aC",
  "team_id": "tm_lbhzBKgFOUnB",
  "webhook_id": "web_u05hx7tvkvd8",
  "transformation_id": "trs_3g5n4Sl0pCxcqc",
  "log_level": "info",
  "logs": [],
  "created_at": "2026-01-14T13:36:36.022428Z",
  "updated_at": "2026-01-14T13:36:36.022428Z",
  "original_event_data": {
    "body": {
      "headers": {
        "content-type": "application/json"
      },
      "body": {
        "type": "order.created",
        "customer": {
          "id": "cust_123",
          "email": "customer@example.com"
        },
        "total": 99.99,
        "timestamp": "2026-01-14T13:36:35.985Z"
      }
    },
    "headers": {
      "content-length": "192",
      "content-type": "application/json",
      "user-agent": "axios/1.11.0",
      "x-hookdeck-original-ip": "::1"
    },
    "parsed_query": {},
    "path": "",
    "query": "",
    "is_large_payload": false
  },
  "transformed_event_data": {
    "body": {
      "headers": {
        "content-type": "application/json"
      },
      "body": {
        "type": "order.created",
        "customer": {
          "id": "cust_123",
          "email": "customer@example.com"
        },
        "total": 99.99,
        "timestamp": "2026-01-14T13:36:35.985Z"
      }
    },
    "headers": {
      "content-length": "192",
      "content-type": "application/json",
      "user-agent": "axios/1.11.0",
      "x-hookdeck-original-ip": "::1",
      "x-api-key": "test_key_123"
    },
    "parsed_query": {},
    "path": "",
    "query": "",
    "is_large_payload": false
  }
}

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 your 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 track 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 has been resolved.
6. Go back to the original issue, click and submit the "Bulk Retry".

Node.js compatibility

Transformations run in a V8 isolate, a sandbox that shares low-level resources with other isolates but keeps their memory and execution separate. The isolate 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').

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