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.
Create and link a transform
- Create it with Create a transform, sending
kind: "destination", anameand the first draft ascode. - Link it by sending its ID as
transformIdwhen you create or update a destination.transformId: nullunlinks it, and later attempts send the payload unchanged. A transform of the other kind, or one from another app, is refused with400.
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.
- Save the draft with Save a transform's draft. Saving replaces the previous draft. It doesn't run or check the code.
- Try it on a sample event, in the console or with Preview a transform. See Test a transform.
- Make it live with Publish a transform. Every attempt of every linked destination runs it from then on. Send the draft's
savedAtas you last read it. If someone saved the draft since, publishing answers409and 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.
async function handler(payload, { type }) {
return Response.json(payload);
}payloadis the parsed payload you sent, not the whole request.- The second argument is the context.
typeis the event type, such ascustomer.created. A transform never receiveschannels: the destination's filters already decided who gets the event. - The
Responseis the standard one from MDN. Its status must be200. Responsesets thecontent-typefrom the body.Response.json,URLSearchParamsandFormDataeach get the matching type, multipart boundary included, without code of your own.- PayloadPuffin always sets
webhook-id,webhook-timestampandwebhook-signatureitself, whatever theResponsehas 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
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
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
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
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:
| Limit | Value |
|---|---|
| CPU time | 50 ms per run |
| Network access | None. A transform can't make HTTP requests |
| Platform access | None. No secrets, storage, or environment variables |
| Returned body | At most 262,144 bytes (256 KiB), as sent |
| Returned headers | At most 65,536 bytes, together with the rest of the result head |
| State between runs | Not 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.
| Failure | Result |
|---|---|
The code throws, or returns something that isn't a Response | The attempt fails and the delivery is retried |
The Response has a status other than 200 | The 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 file | The attempt fails and the delivery is retried |
| The payload you sent isn't valid JSON | The attempt fails and the delivery is retried |
| The body is over 262,144 bytes | The 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, withtype, such ascustomer.created, andpayload, 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.
{
"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:
status | Meaning |
|---|---|
succeeded | delivery.body is the text a delivery would send, and delivery.headers lists its headers, content-type included |
failed | The code threw, didn't return a Response with status 200, or ran for more than 5 seconds |
output_too_large | The 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:
| Status | When |
|---|---|
400 | You sent no event |
404 | The transform doesn't exist |
429 | The app has used its 50 sandbox tests for the UTC day |
502 | The transform runtime didn't run the code at all. Try again later |