From cb6284b66f7b5819a23326cf05caef682b4e88cf Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Mon, 6 Apr 2026 21:43:58 -0400 Subject: [PATCH 1/3] feat: document transient payload passthrough in elements --- .../elements/guides/30_transient_payloads.mdx | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/elements/guides/30_transient_payloads.mdx diff --git a/docs/elements/guides/30_transient_payloads.mdx b/docs/elements/guides/30_transient_payloads.mdx new file mode 100644 index 0000000000..aa2159adbe --- /dev/null +++ b/docs/elements/guides/30_transient_payloads.mdx @@ -0,0 +1,73 @@ +--- +id: transient-payload +title: Transient Payload passthrough +sidebar_label: Transient Payload +--- + +Transient payload is an Ory Kratos concept, that allows users of the APIs to pass data through to webhooks. All self-service Kratos flows support transient payloads, and they are passed through to the webhooks as JSON objects. This allows you to use the data in your webhooks, for example to customize the user experience or to trigger specific actions based on the data. + +Ory Elements allows defining transient payloads on the self-service flow components. To do this, you can use the `transientPayload` prop on the self-service flow components. The value of this prop should be an object that contains the data you want to pass through to the webhooks or a function that returns such an object. The data will be passed through to the webhooks as JSON objects. + + +## Static Transient Payload + +In this example, we define a static transient payload that contains the user's preferred language. This data will be passed through to the webhooks as a JSON object. + +```tsx +import { Registration } from "@ory/elements-react/theme" +import { getRegistrationFlow, OryPageParams } from "@ory/nextjs/app" + +import config from "@/ory.config" +import { headers } from "next/headers" + +export default async function RegistrationPage(props: OryPageParams) { + const flow = await getRegistrationFlow(config, props.searchParams) + + const language = (await headers()).get("Accept-Language") + + if (!flow) { + return null + } + + return ( + + ) +} + +``` + +## Dynamic Transient Payload + +In this example, we define a dynamic transient payload that contains the user's preferred language. The function is called, when the user submits the form, and the API request is made. This allows you to pass dynamic data to the webhooks, based on the user's input or other factors. + +```tsx +"use client" + +import { Registration } from "@ory/elements-react/theme" +import { RegistrationFlow } from "@ory/client-fetch" +import config from "@/ory.config" + +export function RegistrationWithPayload({ flow }: { flow: RegistrationFlow }) { + return { + const referalCode = localStorage.getItem("referal-code") + return { + referalCode, + } + }} + /> +} +``` + +The function also receives the form values as an argument, which allows you to use the user's input to determine the transient payload. In this example, we are retrieving a referral code from local storage and passing it through to the webhooks. From 8d8121c8855bd79bf998ca61a024d4909c29742f Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Mon, 6 Apr 2026 21:49:10 -0400 Subject: [PATCH 2/3] chore: format --- .../elements/guides/30_transient_payloads.mdx | 45 ++++++++++++------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/docs/elements/guides/30_transient_payloads.mdx b/docs/elements/guides/30_transient_payloads.mdx index aa2159adbe..9517d764ee 100644 --- a/docs/elements/guides/30_transient_payloads.mdx +++ b/docs/elements/guides/30_transient_payloads.mdx @@ -4,14 +4,21 @@ title: Transient Payload passthrough sidebar_label: Transient Payload --- -Transient payload is an Ory Kratos concept, that allows users of the APIs to pass data through to webhooks. All self-service Kratos flows support transient payloads, and they are passed through to the webhooks as JSON objects. This allows you to use the data in your webhooks, for example to customize the user experience or to trigger specific actions based on the data. +Transient payload is an Ory Kratos concept, that allows users of the APIs to pass data through to webhooks. All self-service +Kratos flows support transient payloads, and they are passed through to the webhooks as JSON objects. This allows you to use the +data in your webhooks, for example to customize the user experience or to trigger specific actions based on the data. -Ory Elements allows defining transient payloads on the self-service flow components. To do this, you can use the `transientPayload` prop on the self-service flow components. The value of this prop should be an object that contains the data you want to pass through to the webhooks or a function that returns such an object. The data will be passed through to the webhooks as JSON objects. +Ory Elements allows defining transient payloads on the self-service flow components. To do this, you can use the +`transientPayload` prop on the self-service flow components. The value of this prop should be an object that contains the data you +want to pass through to the webhooks or a function that returns such an object. The data will be passed through to the webhooks as +JSON objects. +- [Read more about webhooks in Ory](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) ## Static Transient Payload -In this example, we define a static transient payload that contains the user's preferred language. This data will be passed through to the webhooks as a JSON object. +In this example, we define a static transient payload that contains the user's preferred language. This data will be passed +through to the webhooks as a JSON object. ```tsx import { Registration } from "@ory/elements-react/theme" @@ -37,17 +44,18 @@ export default async function RegistrationPage(props: OryPageParams) { Card: {}, }} transientPayload={{ - language + language, }} /> ) } - ``` ## Dynamic Transient Payload -In this example, we define a dynamic transient payload that contains the user's preferred language. The function is called, when the user submits the form, and the API request is made. This allows you to pass dynamic data to the webhooks, based on the user's input or other factors. +In this example, we define a dynamic transient payload that contains the user's preferred language. The function is called, when +the user submits the form, and the API request is made. This allows you to pass dynamic data to the webhooks, based on the user's +input or other factors. ```tsx "use client" @@ -57,17 +65,20 @@ import { RegistrationFlow } from "@ory/client-fetch" import config from "@/ory.config" export function RegistrationWithPayload({ flow }: { flow: RegistrationFlow }) { - return { - const referalCode = localStorage.getItem("referal-code") - return { - referalCode, - } - }} - /> + return ( + { + const referalCode = localStorage.getItem("referal-code") + return { + referalCode, + } + }} + /> + ) } ``` -The function also receives the form values as an argument, which allows you to use the user's input to determine the transient payload. In this example, we are retrieving a referral code from local storage and passing it through to the webhooks. +The function also receives the form values as an argument, which allows you to use the user's input to determine the transient +payload. In this example, we are retrieving a referral code from local storage and passing it through to the webhooks. From 52f65a3e81223d396d8ab565efdee463767bcab4 Mon Sep 17 00:00:00 2001 From: Jonas Hungershausen Date: Tue, 7 Apr 2026 08:11:39 -0400 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Jonas Hungershausen --- docs/elements/guides/30_transient_payloads.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/elements/guides/30_transient_payloads.mdx b/docs/elements/guides/30_transient_payloads.mdx index 9517d764ee..8d9c756f39 100644 --- a/docs/elements/guides/30_transient_payloads.mdx +++ b/docs/elements/guides/30_transient_payloads.mdx @@ -70,9 +70,9 @@ export function RegistrationWithPayload({ flow }: { flow: RegistrationFlow }) { flow={flow} config={config} transientPayload={(formValues) => { - const referalCode = localStorage.getItem("referal-code") + const referralCode = localStorage.getItem("referral-code") return { - referalCode, + referralCode, } }} />