Skip to main content

Map outbound request bodies

Build outbound request bodies from static values, Data Query fields, Dynamic Inputs, Credentials, and transformations.

Map outbound request bodies

Use outbound Body Elements to build the content Payloads sends to an external API.

The body can be JSON, XML, form URL encoded, or plain text. The principle is the same for each format: model the structure the external API expects, then choose where each runtime value should come from.

For Element basics, see Understand Elements and mapping.

Start with the API shape

Open the external API documentation and identify the request body fields the endpoint expects.

Create the body structure in Payloads before worrying about every value source. For nested JSON or XML, that means building parent and child Elements. For form URL encoded requests, it means creating the key/value pairs the API expects.

The Stripe checkout example uses a form URL encoded body because that is what the Stripe endpoint accepts. Payloads still shows the body as Elements so each value is visible.

The line_items Element is an Array. It is mapped to the OpportunityLineItems child records returned by the Opportunity query, so Payloads can build one Stripe line item for each Salesforce line item.

A Stripe checkout request body showing mapped Elements for mode, customer email, line item amount, success URL, and cancel URL.

The request body mirrors the external API contract while each row keeps its mapping source visible.

Choose the value source

Each outbound Body Element needs a source.

Use Static Value for values that should be the same every time the Payload runs, such as a mode, fixed status, or literal flag.

Use Field when the value should come from a Data Query. This is the right choice for Salesforce record values such as Opportunity Amount, Account Name, or Contact Email.

Use Dynamic Input when the caller supplies the value at runtime. This is useful when a Flow, button, or previous Payload already has the value and does not need another query.

Use Credential when the value should come from the attached Credential.

Use Transformation when the source value is right, but the external API expects a different format.

Map fields from Data Queries

When a Body Element uses a Field source, select the Data Query and field.

In the checkout example, Payloads reads each OpportunityLineItem Unit Price from the Opportunity For Checkout query's OpportunityLineItems child relationship and maps it to Stripe's unit_amount field. A transformation then converts the Salesforce amount into the format required by the API.

Use Configure Data Queries if the query does not exist yet or if the mapping cannot find the field you need.

Understand the index tree

Payloads uses the Element tree to work out which record a field mapping can read from.

An Element outside an Array does not have a current list item. It can map to fields from a single-record Data Query, usually a query with Record Limit set to 1. In the Stripe checkout body, client_reference_id sits outside line_items, so it reads from the single Opportunity record.

An Array Element creates a repeated context. If the Array is mapped to a query or child relationship, every child Element inside the Array can read fields from the current record in that array.

The Element modal showing line_items configured as an Array mapped to the OpportunityLineItems child relationship.

The Array Element defines the repeated record context for every child Element inside it.

In the same checkout body, unit_amount sits inside line_items. That means it can read from the current OpportunityLineItem, not just the parent Opportunity. The same pattern applies to nested arrays: each array adds a new current-record context for its children.

The Element modal showing unit_amount mapped from an OpportunityLineItems field.

A child Element inside an Array can use fields from the current array record, such as the current OpportunityLineItem Unit Price.

If a mapping cannot see the field you expect, check where the Element sits in the tree. Moving an Element into the correct Array often changes which source records are available.

Use Dynamic Inputs for runtime values

Dynamic Inputs are better than hard-coded values when the value changes for each run but is already known by the caller.

In the fulfilment update demo, the Stripe session id is supplied as $STRIPE_SESSION_ID. Payloads maps that input into the outbound body and URL modifier.

An Outbound Webhook Payload showing a Stripe session id supplied as a Dynamic Input.

Dynamic Inputs keep each run flexible without adding unnecessary Salesforce queries.

Keep authentication out of the body where possible

Authentication values usually belong on a Credential, not on the Payload body.

Only put authentication data in the body when the external API specifically requires it there, such as an OAuth token refresh request. For standard API keys, bearer tokens, basic authentication, and custom headers, attach a Credential to the Payload instead.

Request-specific metadata can still live on the Payload. In the checkout example, the idempotency key is a request header based on the Opportunity Id, not part of the Credential.

A Full Callout Payload showing request headers that use Salesforce data for request-specific metadata.

Use Payload-level headers for call-specific values and Credentials for reusable authentication.

Review the runtime body

The Job record shows the body Payloads actually sent.

Use it to check whether static values, query fields, Dynamic Inputs, and transformations resolved the way you expected. This is especially useful when the external API rejects the request but the Payload configuration looks correct.

A Job record showing the outbound body generated for a Stripe checkout run.

The Job body is the source of truth for what Payloads sent to the external API.

What to check

Before testing, check that:

  • the outbound content type matches the API endpoint

  • body paths or parameter names match the API documentation

  • required fields have a source

  • query-based Elements reference the right Data Query and field

  • Dynamic Input names match the runtime caller

  • transformations are applied only where the external API needs a different format

  • sensitive authentication values are handled by a Credential where possible

After testing, compare the Job outbound body with the API documentation and the API response.

Did this answer your question?