Transformations

Transformations allow you to write JavaScript code that modifies webhook properties before they’re delivered to your endpoint. You can change the HTTP method, target URL, payload, add custom headers, or even cancel specific webhooks.

Use Cases

Transformations are useful when you need to:

Modify payloads to match your system’s expected format
Redirect webhooks to different URLs based on payload content
Add custom headers for authentication or routing
Filter webhooks by canceling ones you don’t need
Transform data (e.g., convert currency formats, rename fields)

Accessing Transformations

Go to the Webhooks settings in your dashboard
Click on an endpoint to view its details
Navigate to the Advanced tab
Scroll down to the Transformations card
Toggle the switch to enable transformations

Writing a Transformation

Transformations use a JavaScript handler function that receives the webhook data and returns the modified version.

Input Properties

The handler function receives an object with these properties:

Property	Type	Description
`method`	string	HTTP method (`"POST"` or `"PUT"`)
`url`	string	The endpoint URL
`payload`	object	The webhook payload as JSON
`eventType`	string	The event type (read-only)

Return Properties

Return the same object with your modifications. You can also add:

Property	Type	Description
`cancel`	boolean	Set to `true` to cancel this webhook
`headers`	object	Custom headers to add to the request

Examples

Modify the Payload

Flatten nested data or rename fields:

function handler(webhook) {
  // Add a custom field
  webhook.payload.source = "storekit";
  
  // Rename a field
  webhook.payload.orderId = webhook.payload.order_id;
  delete webhook.payload.order_id;
  
  return webhook;
}

Redirect Based on Payload

Send webhooks to different URLs based on content:

function handler(webhook) {
  if (webhook.payload.priority === "high") {
    webhook.url = "https://example.com/webhooks/priority";
  }
  return webhook;
}

Add Custom Headers

Include additional headers for your endpoint:

function handler(webhook) {
  webhook.headers = {
    "X-Custom-Header": "my-value",
    "X-Store-ID": webhook.payload.store_id
  };
  return webhook;
}

Cancel Specific Webhooks

Filter out webhooks you don’t want to receive:

function handler(webhook) {
  // Don't send webhooks for test orders
  if (webhook.payload.test_mode === true) {
    webhook.cancel = true;
  }
  return webhook;
}

Change HTTP Method

Switch from POST to PUT if needed:

function handler(webhook) {
  webhook.method = "PUT";
  return webhook;
}

Testing Transformations

Before saving your transformation:

Click Test in the transformation editor
Select an event type or enter a custom payload
Review the transformed output
Verify the changes are correct before saving

Canceled webhooks appear as successful deliveries in your logs. Use cancellation carefully to avoid missing important events.

Keep transformations simple and fast. Complex logic may cause timeouts or unexpected behavior.

Developers

Guides

Webhooks

Transformations

Use Cases

Accessing Transformations

Writing a Transformation

Input Properties

Return Properties

Examples

Modify the Payload

Redirect Based on Payload

Add Custom Headers

Cancel Specific Webhooks

Change HTTP Method

Testing Transformations

​Use Cases

​Accessing Transformations

​Writing a Transformation

​Input Properties

​Return Properties

​Examples

​Modify the Payload

​Redirect Based on Payload

​Add Custom Headers

​Cancel Specific Webhooks

​Change HTTP Method

​Testing Transformations

Use Cases

Accessing Transformations

Writing a Transformation

Input Properties

Return Properties

Examples

Modify the Payload

Redirect Based on Payload

Add Custom Headers

Cancel Specific Webhooks

Change HTTP Method

Testing Transformations