Transformations

Ingest Transformations are a powerful Svix feature that allows the modification of certain webhook properties in-flight. With transformations, you can write JavaScript code to change a webhook’s HTTP method, target URL, and body payload before it’s sent to your endpoint.

Using Transformations

Ingest Transformations are available in all plans. To use them, after creating an endpoint in a Source, go to the ‘Advanced’ tab and scroll down to the ‘Transformations’ card:

An endpoint’s Transformation can be enabled or disabled at any time by toggling the switch on this card.

You can write Javascript code to edit an endpoint’s Transformation, and test your code against a sample incoming payload to see the result.

How to write a Transformation

Svix expects a Transformation to declare a function named handler. Svix will pass an object with the following properties to the function:

• method, a string representing the HTTP method the webhook will be sent with. It is always "POST" by default, and its only valid values are "POST" or "PUT".
• url, a string representing the destination endpoint’s URL. It can be changed to any valid URL.
• payload, which contains the webhook’s payload as a JSON object. It can be changed as needed.
• eventType, a string representing the event type. Changes to it are ignored. This will always have the value svix.in for ingest events
• transformationsParams, additional parameters made available in ingest; see below for details

The Transformation must return the same object, but may modify its properties as described above. In addition to the ones listed above, it can also set the following properties on the returned object:

• cancel, a boolean which controls whether or not to cancel the dispatch of a webhook. This value defaults to false.
• headers, an object with keys being HTTP header names and values being the associated header values. Headers set here take precedence over endpoint headers.

An example Transformation

Suppose that sometimes, you want to redirect webhooks to a custom URL instead of the endpoint’s defined URL. And you only want to do this redirect if a custom URL is present in the webhook payload. You can write a transformation like this:

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

Great, the webhook is redirected to the custom URL if the customUrl property exists on the payload. Otherwise, it is sent to the endpoint’s defined URL.

Ingest-Specific Transformations Params

Transformations called from an Ingest request will receive additional parameters under the transformationsParams property. Specifically:

• transformationsParams.headers will be a string/string key-value map containing the headers of the input request. If a header is duplicated on the input request, the values will be concatenated with ”, ”, as per RFC 9110 § 5.2 .
• transformationsParams.headers.svix-ingest-query contains the un-parsed query string (the part after the ? on the request URL)
• transformationsParams.headers.svix-ingest-trailing-path-segments contains any parts of the URL after the token, not including the first /.

If your source URL is https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567 and your provider makes a request to https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567/foo/bar/baz?qux=duck, transformationsParams.headers["svix-ingest-query"] will contain the string qux=duck and transformationsParams.headers["svix-ingest-trailing-path-segments"] will contain the string foo/bar/baz.