Transformations (Preview)

Transformations allow you to modify the payload of a webhook event received within Hookdeck. We allow for arbitrary transformations of any of the request data using Javascript (ES6). The following is an example of a transformation that will add a new header to the payload.

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

Use cases

Because transformations are Javascript handlers, it offers a lot of flexibility. While we can't foresee all use cases, here are a few examples of how it can be used:

  • Change your payload format. Transform allows the resulting request to be a different format. You might be receiving your payload as XML and would rather send it as JSON to your destination.
  • Unified model from multiple platforms. Using transformation, you can merge different webhooks with different shapes into a single "definition" for that model. You could, for instance, standardize WooCommerce order webhooks and Shopify order webhooks into a single order entity.
  • Format your request to be compatible with another API. By adding API keys or formatting the payload differently, you could make your payload compatible as an API request to another service, such as Slack.

If you have other use cases, please let us know!


Preview

Transformation is in Early Preview. You may request access by contacting us via live chat or email at [email protected].

By using Transformations in preview, you accept that:

  • You cannot run more than 1 million transformations per month;
  • Your transformations could be disabled at any time without heads up;
  • The Hookdeck team may view and audit your transformation code (not environment variables);
  • The Hookdeck team might introduce backward-incompatible changes to the transformation functionality or API.

Warning: Transformations should not be used for mission-critical use cases at this time. We are currently gathering feedback on the implementation and are working toward general availability.

Limitations

Transformations have some important limitations to keep in mind. Some of those limitations are still subject to change.

  • The transformation runtime cannot perform any IO or access any external resources such as the network or filesystem;
  • Only the following node modules can be imported: crypto, URL;
  • The transformation runtime is limited to a maximum of 1 second execution time;
  • The transformation code is limited to 100kb.

How it works

Transformation are applied as connections Rules. Each event received on the connection will be run against your transformation handler, and the result will be used as the new request for the event. Your destination will receive the new request. Filter rules are run AFTER the transformation has been performed.

Handler

The transformation handler is a function that is invoked a request and context object. The request is the request that was received from the connection. The context object is an object that contains the connection the transformation is currently running on. Specifically, the request type is:

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

And context:

{
  connection: WebhookConnection
}

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

The handle must return a valid request object with a valid content-type header. The returned parsed_query is ignored, and the query will be reparsed from the query that is returned.

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

Creating a transformation

Transformations are created just like any other Rule. The difference is that a Transform Rule is attached a transformation that can be shared between multiple connections.

Enviroment variables

Transformations support environment variables to store secrets. You can access your variable on the process.env object. For instance, if you have a variable called TEST, you'd read the value with process.env.TEST.

You can list new key-value pairs in the "Variables" dropdown.

Testing your transformation

In the transformation edit, you can "Run" your transformation by using the request on the left-hand side as input for the transformation. Any lines logged to the console will be printed in the console on the bottom of the code editor.

Troubleshoot a transformation

Transformation logs can be found in the transformation options. Each transformation input and output can be inspected.