Data Transformation
The Pakk webhooks framework enables advanced use cases with data transformation using Javascript code you write yourself.
Last updated
The Pakk webhooks framework enables advanced use cases with data transformation using Javascript code you write yourself.
Last updated
If you have control over the server code at the webhook endpoint, then the shape of the data being sent is less important as you will be able to parse and process the data as needed with your own server-side code.
However, when the webhook endpoint is outside of your control, for example, if it is part of a third-party SaaS application, you'll probably need the shape of the webhook data to conform to a specific model. In this case, you can use Pakk's 'webhook data transformation' functionality to sculpt the request body that is sent to the webhook.
Before you can run any data transformation code, you need to check 'Enable Transformation' on the webhook configuration screen. This will activate a code input box for the transformation code.
Enter the Javascript code to be run over the data. You'll need to take the following into account:
Your code is executed in the cloud in a sandboxed Deno environment (as opposed to Node). Deno is mostly similar to Node, but if you need to get into more advanced use cases, you'll need to consult the Deno documentation: https://docs.deno.com
There are limits to the complexity of the code and the compute time it can take up - if you start hitting these limits, you'll be able to see the errors on the Webhook log
The input data to your code is as a Javascript object data. This data object has one or two sub objects: newState (always present) and previousState (only present for updates). Each of these obejcts is the full JSON representation of the record.
The outut of your code should be a Javascript object with the same name, data
If the business logic in your transformation code needs to abort execution of the webhook for any reason, simple return 0, null or false.
For most use cases, the easist thing to do is probably edit the input data and return it. For example, seting the memo field on an order could be done like this:
Alternatively, if you only need to return a small subset of fields, for example, you only need to extract the customer's email address from an order, you could start with a blank data object, like this:
As always, you can view the shape of the input data in the regular API docs, or simply send test webhook requests to a testing service without any transformations to directly see the untransformed data shape.
Remember that any transformations you apply are also applied when you test the webhook, making development easy.
Sometimes you might need to take action depending on how a record has changed - this can be achieved by comparing the previous state to the new state. For example, you could determine if an order has just been dispatched by comparing the new status to the previous.
