Transformations

Transformations allow you to modify webhook properties before delivery—change the HTTP method, target URL, or payload structure. Write JavaScript code that runs on each webhook to customize how events are delivered to your endpoint.

Enable Transformations

Transformations are configured per endpoint:

Open your endpoint

Go to Dashboard → Developers → Webhooks and select an endpoint.

Navigate to Advanced

Click the Advanced tab.

Enable Transformations

Toggle Enable Transformation and click Edit to write your code.

Write a Transformation

Transformations declare a handler function that receives the webhook object and returns a modified version.

Input properties

Property	Type	Description
`method`	string	HTTP method (`"POST"` or `"PUT"`)
`url`	string	Endpoint URL (can be changed)
`payload`	object	Webhook payload (can be modified)
`eventType`	string	Event type (read-only)

Output properties

Return the same object with modifications. You can also set:

Property	Type	Description
`cancel`	boolean	Set `true` to skip delivery (defaults to `false`)
`headers`	object	Custom headers to include in the request

Examples

Redirect to custom URL

Route webhooks to a URL specified in the payload:

function handler(webhook) {
  if (webhook.payload.customUrl) {
    webhook.url = webhook.payload.customUrl;
  }
  return webhook;
}

Add custom headers

Include authentication or tracking headers:

function handler(webhook) {
  webhook.headers = {
    "X-Custom-Auth": "your-auth-token",
    "X-Request-ID": webhook.payload.id
  };
  return webhook;
}

Filter events

Cancel delivery for specific conditions:

function handler(webhook) {
  // Skip test events in production
  if (webhook.payload.data?.test === true) {
    webhook.cancel = true;
  }
  return webhook;
}

Transform payload structure

Reshape the payload to match your system’s expected format:

function handler(webhook) {
  // Flatten nested structure
  webhook.payload = {
    event: webhook.eventType,
    id: webhook.payload.data?.id,
    amount: webhook.payload.data?.amount,
    currency: webhook.payload.data?.currency,
    timestamp: webhook.payload.created_at
  };
  return webhook;
}

Change HTTP method

Some systems expect PUT instead of POST:

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

Testing Transformations

Before saving, test your transformation against sample payloads:

Click Test in the transformation editor
Select an event type or enter a custom payload
Review the transformed output
Verify the URL, method, headers, and payload are correct

Canceled webhooks appear as successful deliveries in logs. Use cancel sparingly to avoid missing important events.

Introduction

Objects

Enable Transformations

Write a Transformation

Input properties

Output properties

Examples

Redirect to custom URL

Add custom headers

Filter events

Transform payload structure

Change HTTP method

Testing Transformations

​Enable Transformations

​Write a Transformation

​Input properties

​Output properties

​Examples

​Redirect to custom URL

​Add custom headers

​Filter events

​Transform payload structure

​Change HTTP method

​Testing Transformations

Enable Transformations

Write a Transformation

Input properties

Output properties

Examples

Redirect to custom URL

Add custom headers

Filter events

Transform payload structure

Change HTTP method

Testing Transformations