Skip to main content
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:
1

Open your endpoint

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

Navigate to Advanced

Click the Advanced tab.
3

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

PropertyTypeDescription
methodstringHTTP method ("POST" or "PUT")
urlstringEndpoint URL (can be changed)
payloadobjectWebhook payload (can be modified)
eventTypestringEvent type (read-only)

​
Output properties

Return the same object with modifications. You can also set:
PropertyTypeDescription
cancelbooleanSet true to skip delivery (defaults to false)
headersobjectCustom 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:
  1. Click Test in the transformation editor
  2. Select an event type or enter a custom payload
  3. Review the transformed output
  4. 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.