Skip to content
PayloadPuffin.
Join the waitlist

Transforms

Your event payload has one shape, and one receiver wants another, with different field names, fewer fields, an extra header, or a form instead of JSON. A transform is a short piece of JavaScript, attached to a destination, that turns the payload into the request that destination receives. Without one, the destination receives the payload bytes exactly as you sent them.

A transform belongs to the app, not to one destination, so you write it once and link it from as many destinations as need it. Publishing a fix then changes what every one of them sends. A source can link a transform too, one that builds the event from each request it receives: see Source transforms. A transform has a name and a kind, destination or source, and links only to resources of its kind.

  1. Create it with Create a transform, sending kind: "destination", a name and the first draft as code.
  2. Link it by sending its ID as transformId when you create or update a destination. transformId: null unlinks it, and later attempts send the payload unchanged. A transform of the other kind, or one from another app, is refused with 400.

Each destination links at most one transform. Even when several destinations link the same transform, each one runs it on its own: nothing one destination's run leaves behind reaches another's.

Draft and live

A transform has a saved draft and live code. Deliveries run only the live code, so you can edit and test a draft without changing what your receivers get.

  1. Save the draft with Save a transform's draft. Saving replaces the previous draft. It doesn't run or check the code.
  2. Try it on a sample event, in the console or with Preview a transform. See Test a transform.
  3. Make it live with Publish a transform. Every attempt of every linked destination runs it from then on. Send the draft's savedAt as you last read it. If someone saved the draft since, publishing answers 409 and changes nothing, so you never publish code you haven't seen.

Get a transform returns the draft with its savedAt, the live code with its publishedAt, unpublishedChanges, which is true when the draft isn't what deliveries run, and the destinations and sources that link it. Delete a transform is refused with 409 while anything links it, and the answer says how many destinations and sources do. Send unlink=true to unlink them and delete it in one step; they then run no transform.

A draft that was never published changes nothing: linked destinations send payloads unchanged until you publish. Publishing keeps no copy of the previous live code, and saving keeps no copy of the previous draft. Code is at most 16,384 characters.

A destination transform needs the destinations:read scope to read and destinations:write for everything else. In the console, the Transforms page lists and creates them, and a destination's Transform field picks one.

What a transform receives and returns

A transform defines async function handler(payload, { type }). Return a Response; its body and headers are what PayloadPuffin sends to the destination.

JavaScript
async function handler(payload, { type }) {
	return Response.json(payload);
}
  • payload is the parsed payload you sent, not the whole request.
  • The second argument is the context. type is the event type, such as customer.created. A transform never receives channels: the destination's filters already decided who gets the event.
  • The Response is the standard one from MDN. Its status must be 200.
  • Response sets the content-type from the body. Response.json, URLSearchParams and FormData each get the matching type, multipart boundary included, without code of your own.
  • PayloadPuffin always sets webhook-id, webhook-timestamp and webhook-signature itself, whatever the Response has for those names.

A string is sent as text/plain, as with fetch, even when it holds JSON: new Response('{"a":1}') arrives as text/plain;charset=UTF-8. To send JSON, use Response.json.

Send JSON with an extra header

JavaScript
async function handler(payload, { type }) {
	return Response.json(
		{ id: payload.customerId, email: payload.email },
		{ headers: { 'x-customer-plan': payload.plan } },
	);
}

The receiver gets content-type: application/json and the x-customer-plan header.

Send a form

JavaScript
async function handler(payload, { type }) {
	return new Response(new URLSearchParams({ event: type, email: payload.email }));
}

The receiver gets content-type: application/x-www-form-urlencoded;charset=UTF-8 and a body such as event=customer.created&email=ada%40example.com.

Send multipart

JavaScript
async function handler(payload, { type }) {
	const form = new FormData();
	form.set('event', type);
	form.set('email', payload.email);
	return new Response(form);
}

The receiver gets content-type: multipart/form-data with a boundary, and a body split on that same boundary.

Send plain text

JavaScript
async function handler(payload, { type }) {
	return new Response(`${type}: ${payload.email}`);
}

The receiver gets content-type: text/plain;charset=UTF-8. To send text with another type, such as XML, set it yourself: new Response(xml, { headers: { 'content-type': 'application/xml' } }).

Where it runs and what it can do

Each transform runs in its own isolated sandbox, separate from other destinations and other apps. A preview runs in a sandbox of its own, so it never shares state with your live deliveries. The sandbox sets hard limits:

LimitValue
CPU time50 ms per run
Network accessNone. A transform can't make HTTP requests
Platform accessNone. No secrets, storage, or environment variables
Returned bodyAt most 262,144 bytes (256 KiB), as sent
Returned headersAt most 65,536 bytes, together with the rest of the result head
State between runsNot kept. Globals may survive or reset at any time

A transform maps one payload to one request and nothing else. Anything that needs a lookup belongs in your own code, before you send the event.

When it runs

The transform runs on every attempt, right before the request is signed and sent. The signature covers the transformed bytes, so your receiver verifies exactly what it got. See Verify signatures.

Every attempt reads the destination's current live code. A fix you publish reaches deliveries that are already retrying: their next attempt runs it. If you remove the transform, their next attempt sends the payload unchanged. If a delivery has already failed, publish the fix and then resend it.

The bytes in the event receipt count the payload you sent, before any transform.

What happens when it fails

A transform that fails sends nothing. PayloadPuffin doesn't fall back to the original payload, because the destination asked for the transformed one.

FailureResult
The code throws, or returns something that isn't a ResponseThe attempt fails and the delivery is retried
The Response has a status other than 200The attempt fails and the delivery is retried
Response.json can't serialize the value (a BigInt, a cycle)The attempt fails and the delivery is retried
The body isn't UTF-8 text, such as an image or a binary fileThe attempt fails and the delivery is retried
The payload you sent isn't valid JSONThe attempt fails and the delivery is retried
The body is over 262,144 bytesThe delivery fails at once, without retries

A failed transform still counts as an attempt. It has no HTTP status code, and its error says what went wrong and how to fix it, for example "Return a Response, such as return Response.json(payload)." Retries follow the normal schedule, so a bug fails every attempt until you publish a fix, and after eight the delivery is failed. See Retries.

Transform failures aren't held against your receiver. They don't count toward the destination's failure streak or its health, and they never start a cooldown.

Test a transform

There are two ways to try code on a sample event. Neither saves anything, sends anything or counts as a transform run.

In the console, write the whole sample event in the Event editor, type and payload included, as you would in Send test event. Both tests use it. Channels aren't passed to the transform.

In your browser. As you type, the console runs the code in your browser tab, in a worker with no access to your console session, and shows the result under Delivery. It's free, instant and has no limit. It follows the same rules as a real delivery: the code receives payload and { type }, returns a Response with status 200, and the body may be at most 262,144 bytes (256 KiB). The result shows the body as text and the headers a delivery would send, so a missing await or a text/plain body shows up at once. A run stops after 2 seconds, so code that never ends shows as a failure instead of freezing the tab.

It can differ from a real delivery at the edges: it has no 50 ms CPU limit and runs on your browser's JavaScript engine. It's also not a security boundary, so don't run code you don't trust on a sample that holds secrets. Use it as the quick check, and test in the sandbox before you publish.

In the sandbox. Test in sandbox in the console, or the preview operation below, runs the code in the same kind of sandbox a delivery uses. Each app may run 50 sandbox tests a day, counted by UTC day, whatever their outcome and whether or not the code changed. Once the 50 are used, the API answers 429 with a Retry-After header, the number of seconds until 00:00 UTC, and doesn't run the code. The browser test still works.

Preview a transform

Preview a transform is the sandbox test. It runs code on a sample event and returns what a delivery would send. Send:

  • event: the sample event, with type, such as customer.created, and payload, any JSON value, as you'd send it with an event.
  • code: optional. The code to run, such as unsaved changes in your editor. Leave it out to run the saved draft.
JSON
{
	"event": {
		"type": "customer.created",
		"payload": { "customerId": "cus_1", "email": "ada@example.com", "plan": "pro" }
	}
}

Any run that executed answers 200 with a status, and with budget, which has limit, remaining and resetsAt for the day's sandbox tests:

statusMeaning
succeededdelivery.body is the text a delivery would send, and delivery.headers lists its headers, content-type included
failedThe code threw, didn't return a Response with status 200, or ran for more than 5 seconds
output_too_largeThe body is over 262,144 bytes. A delivery would fail without retries

error explains a run that didn't succeed. Code that doesn't compile, throws or runs too long answers 200 with status failed. The other answers are:

StatusWhen
400You sent no event
404The transform doesn't exist
429The app has used its 50 sandbox tests for the UTC day
502The transform runtime didn't run the code at all. Try again later