> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transformations

> Modify webhook properties in-flight using JavaScript code.

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:

<Steps>
  <Step title="Open your endpoint">
    Go to **Dashboard → Developers → Webhooks** and select an endpoint.
  </Step>

  <Step title="Navigate to Advanced">
    Click the **Advanced** tab.
  </Step>

  <Step title="Enable Transformations">
    Toggle **Enable Transformation** and click **Edit** to write your code.
  </Step>
</Steps>

## 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:

```javascript theme={"system"}
function handler(webhook) {
  if (webhook.payload.customUrl) {
    webhook.url = webhook.payload.customUrl;
  }
  return webhook;
}
```

### Add custom headers

Include authentication or tracking headers:

```javascript theme={"system"}
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:

```javascript theme={"system"}
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:

```javascript theme={"system"}
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:

```javascript theme={"system"}
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

<Warning>
  Canceled webhooks appear as successful deliveries in logs. Use `cancel` sparingly to avoid missing important events.
</Warning>