Skip to main content
Webhook transformations let you modify the payload before it’s delivered to your endpoint. This is useful for:
  • Reducing payload size — Remove large fields like run.run_message_history to significantly decrease payload size
  • Reshaping the schema — Transform the data structure to match what your system expects
  • Filtering data — Remove fields you don’t need
Transformations run server-side before the webhook is sent, so your endpoint receives exactly what you want.

​
Enabling Transformations

1

Open the Webhooks portal

Navigate to the Webhooks tab in your Cyberdesk dashboard.
2

Select your endpoint

Click on the Endpoints tab and select the endpoint you want to transform.
3

Open Advanced settings

Click on the Advanced sub-tab within the endpoint details.
4

Enable transformations

Toggle Enable Transformation to on.
5

Edit your transformation

Click Edit Transformation next to the toggle to open the transformation editor.
6

Write and test your code

Write your JavaScript transformation function, then use the Test feature to verify it works with sample payloads.

​
Writing a Transformation

Transformations are JavaScript functions that receive the webhook data and return a modified version. The function must be named handler and receives an object with these properties:
PropertyDescription
payloadThe webhook payload (JSON object) — modify as needed
methodHTTP method ("POST" or "PUT") — can be changed
urlEndpoint URL — can be changed to redirect
eventTypeEvent type string (changes ignored)
transformationsParamsObject passed via the create-message API (changes ignored)
The function must return the same object, but may modify its properties as described above. You can also set these additional properties on the returned object:
PropertyDescription
cancelBoolean to cancel dispatch (defaults to false)
headersObject of HTTP headers to add (takes precedence over endpoint headers)

​
Example: Remove Message History

The run_message_history field can be very large. Remove it to reduce payload size: 
function handler(webhook) {
  if (webhook.payload.run && webhook.payload.run.run_message_history) {
    delete webhook.payload.run.run_message_history;
  }
  return webhook;
}

​
Example: Extract Only What You Need

Keep just the essential fields for your downstream system: 
function handler(webhook) {
  const run = webhook.payload.run;
  
  // Replace payload with only the fields you need
  webhook.payload = {
    event_type: webhook.payload.event_type,
    run_id: run.id,
    status: run.status,
    output_data: run.output_data,
    workflow_id: run.workflow_id,
    completed_at: run.ended_at
  };
  
  return webhook;
}

​
Example: Cancel Webhooks Conditionally

You can cancel delivery for certain events: 
function handler(webhook) {
  // Don't send webhooks for cancelled runs
  if (webhook.payload.run?.status === "cancelled") {
    webhook.cancel = true;
  }
  return webhook;
}
Cancelled messages appear as successful dispatches in the logs but are not actually sent to your endpoint.

​
Example: Add Custom Headers

Add headers for routing or authentication on your end: 
function handler(webhook) {
  webhook.headers = {
    "X-Workflow-Id": webhook.payload.run?.workflow_id || "",
    "X-Run-Status": webhook.payload.run?.status || ""
  };
  return webhook;
}

​
Testing Your Transformation

The transformation editor includes a test panel where you can:
  1. Select an event type to get a sample payload
  2. Or paste a custom payload
  3. Run your transformation
  4. See the resulting webhook that would be sent
Always test your transformation before saving to ensure it produces the expected output.

​
Common Issues

Make sure the Enable Transformation toggle is on. The toggle and edit button are on the same line in the Advanced tab.
Verify you’re returning the modified webhook object from your handler function. If you forget to return, the original payload is sent.
// ❌ Wrong - no return
function handler(webhook) {
  delete webhook.payload.run.run_message_history;
}

// ✅ Correct - returns modified webhook
function handler(webhook) {
  delete webhook.payload.run.run_message_history;
  return webhook;
}
Check the browser console for syntax errors. Common issues:
  • Missing semicolons or brackets
  • Accessing properties on undefined (use optional chaining: webhook.payload.run?.status)
  • Invalid JSON in test payloads
Your transformation might be throwing an error. Wrap risky operations in try/catch:
function handler(webhook) {
  try {
    if (webhook.payload.run) {
      delete webhook.payload.run.run_message_history;
    }
  } catch (e) {
    // Log error but don't break delivery
    console.error("Transformation error:", e);
  }
  return webhook;
}
If your payloads are still too large after removing run_message_history, consider removing other large fields like run.trajectory or creating a minimal payload with only the fields you need.

​
Learn More

For detailed documentation on writing transformations, including advanced patterns and the complete API reference, see the Svix Transformations documentation.