Receive an inbound webhook and update Salesforce

Use this recipe when another system sends an event to Salesforce and Payloads should turn that event into Salesforce records.

Common examples are payment events, order status updates, fulfilment notifications, customer profile changes, and platform callbacks. The external system sends the request. Payloads parses it, maps the values, writes Salesforce records, and creates a Job that shows what happened.

For the detailed inbound Payload article, see Configure an Inbound Payload that writes to Salesforce.

What you are building

The finished setup has five parts.

A Salesforce Site exposes the public route.
An Endpoint record connects the public route to the Payload.
An Inbound Payload models the request body, headers, and parameters.
Data Targets define the Salesforce records to create, update, or upsert.
Target Fields map inbound values into Salesforce fields.

Start in a sandbox and use a sample webhook payload from the external system.

Create the Inbound Payload

Create a Payload with the type for inbound writes to Salesforce.

Set the Inbound Content Type to match the request the external system sends. Most webhook APIs send JSON, but use the content type the external system actually sends.

Configure the request body, headers, and parameters that Payloads needs. You do not need to model every value in the webhook. Model the values you need for matching, writing, branching, or troubleshooting.

The inbound request body UI showing JSON Elements Payloads can read from the webhook request.

The inbound body model tells Payloads which request values are available for mapping.

For request setup, see Configure inbound body, headers, and parameters.

Create the Endpoint

Create an Endpoint from the Payload.

Choose the Salesforce Site, Endpoint Name, and HTTP Method. Payloads generates the public URL for the external system.

Use Echo Mode only for connectivity testing. Turn it off before the webhook is live.

The Endpoint modal showing a Salesforce Site, generated public URL, selected method, Echo Mode, and endpoint secret settings.

The generated Endpoint URL is what the external system calls.

For Site setup, see Set up inbound endpoints and Sites.

Map the Salesforce write

Create one or more Data Targets.

Use a single-record target when one webhook should update one Salesforce record. Use a multi-record target when the webhook contains an array and each array entry should create or update one Salesforce record.

For multi-record targets, choose the source array carefully. Each entry in that source array becomes one record in the target list.

The Data Target modal showing a multi-record target mapped to a source array.

A multi-record Data Target needs a source array so Payloads knows how many Salesforce records to build.

Then add Target Fields. Map each Salesforce field from the inbound body, header, parameter, static value, global variable, Credential value, query result, or previous Data Target result.

For target setup, see Configure Data Targets and Map Data Target fields.

Test with a real sample request

Send a representative webhook request from the external system or an API client.

Then open the Job and inspect the inbound data before checking Salesforce records. The Job should show the inbound body, headers, parameters, target output, response status, and any error message.

A Stripe event Job showing Data Target results and the field values Payloads attempted to write.

Target output shows what Payloads attempted to write for each Data Target.

If no Job is created, check the Site, URL, method, Endpoint Name, and guest user permissions. If a Job is created but fails, use the Job details to fix parsing, matching, target fields, or Salesforce validation errors.

Production checks

Before giving the Endpoint URL to the external system, confirm:

the Site is active
the Site Guest User has only the access it needs
the Endpoint method matches the external webhook
Echo Mode is off
required request values are present in the sample payload
target matching cannot update the wrong Salesforce record
the response body and status are what the external system expects

For the wider checklist, see Secure Payloads for production.