Home / admin / outbound-message-setup

outbound-message-setup

Use when configuring Workflow-based Outbound Messages to push SOAP payloads to external endpoints — endpoint setup, field selection, retry behavior, and delivery monitoring. NOT for the listener's session ID callback into Salesforce — use integration/outbound-messages-and-callbacks. NOT for JSON webhooks or Flow-triggered pushes — use integration/outbound-webhook-from-salesforce. Keywords: WorkflowOutboundMessage, outboundMessages, endpointUrl, includeSessionId, integrationUser, useDeadLetterQueue, apiVersion, SOAP Ack, .workflow file, approval outbound message action.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Reliability
• Operational Excellence

• outbound-message
• workflow
• integration-admin
• outbound-message-setup
• soap-delivery
• retry
• workflow-metadata
• metadata-api

Open the skill folder on GitHub

Outbound Message Setup

This skill activates when a practitioner needs to configure Salesforce Outbound Messages — the built-in SOAP-based notification mechanism that Workflow Rules use to push record data to external endpoints. It covers the acknowledgment format the external endpoint must return, the retry behavior, and the most critical anti-pattern: assuming an HTTP 200 response is sufficient for the external system to stop receiving retries.

Before Starting

Gather this context before working on anything in this domain:

• Outbound Messages are workflow and approval actions — not Flow actions: The Metadata API guide defines them as "workflow and approval actions that send the information you specify to an endpoint you designate" (api_meta.txt L140313–140315). OutboundMessage is a value of the WorkflowActionType enum (L139961) and appears in ApprovalProcess action blocks (L23615–23641). It is not a Flow element. If the triggering automation is a Flow or Apex, this skill does not apply — use Platform Events or direct API calls instead.
• The "User to send as" decides what the endpoint can see: "The chosen user controls data visibility for the message that is sent to the endpoint" (Defining Outbound Messaging). integrationUser is not bookkeeping — it is the field- and record-level filter on the payload, and it is the identity SessionId represents.
• The definition always lives in workflows/<Object>.workflow: There is one .workflow file per standard or custom object that has workflow, stored in the workflows directory (L139896–139898). Even an outbound message used only by an approval process is declared in the outboundMessages array of that file (L139931). Retrieve before you edit.
• SOAP only — no JSON: Outbound Messages deliver SOAP 1.1 XML. The external endpoint must be able to parse XML SOAP envelopes and return a specific SOAP acknowledgment response. Systems that only accept JSON cannot use Outbound Messages without a SOAP-to-JSON translation layer.
• Critical acknowledgment behavior: The listener must return a notificationsResponse, whose schema in the outbound messaging WSDL is a single boolean: <element name="Ack" type="xsd:boolean"/>. The SOAP API Developer Guide calls it "the schema for sending an acknowledgment (ack) response to Salesforce" and its sample listener is one line of logic — r.Ack = true (Understanding Outbound Messaging, Building a Listener). An HTTP 200 with any other body — empty, JSON, plain text — carries no Ack, so the message is redelivered.

Questions to Ask Before Configuring

Ask these before the first <outboundMessages> element is written. Each one maps to a failure in references/gotchas.md; an agent that skips them produces a .workflow file that deploys clean and delivers nothing.

What a proper configuration adds over just creating an outbound message in Setup: the apiVersion and field list are in version control where a listener-breaking change is reviewable, the session-ID decision is recorded rather than inherited from a Setup default, and the dead-letter/reconciliation answer exists before the first 24-hour drop instead of after it.

Core Concepts

Metadata Shape

WorkflowOutboundMessage (api_meta.txt L140312–140371) — the fields you actually write:

The rule that fires it is a WorkflowRule <actions> block whose type is OutboundMessage and whose name matches the outbound message's fullName (L139952–139966). Full deployable XML: references/metadata-examples.md.

The notifications() Envelope

Outbound messaging "uses the notifications() call to send SOAP messages over HTTP(S) to a designated endpoint when triggered by a workflow rule" (Understanding Outbound Messaging). The WSDL's notifications element is a fixed sequence:

Two consequences the rest of this skill turns on:

• One message can carry up to 100 records. Notification is maxOccurs="100", and the response carries a single Ack for the whole message. A listener that half-processes a batch and returns Ack=true discards the remainder — see gotcha 10.
• Idempotency is the listener's job, and the guide names the key: "Each message Notification also has the object ID. Use the object ID to track redelivery attempts of notifications you've already processed."

Delivery and Acknowledgment

1. Salesforce sends a SOAP payload to the configured endpoint.
2. The listener must return a notificationsResponse — "the schema for sending an acknowledgment (ack) response to Salesforce", whose entire content is <element name="Ack" type="xsd:boolean"/>:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <notificationsResponse xmlns="http://soap.sforce.com/2005/09/outbound">
      <Ack>true</Ack>
    </notificationsResponse>
  </soapenv:Body>
</soapenv:Envelope>

The target namespace is http://soap.sforce.com/2005/09/outbound — the WSDL's own targetNamespace. If the external system returns HTTP 200 with any body that does not carry Ack in that namespace — an empty body, a JSON response, a different namespace — there is no acknowledgment and Salesforce redelivers. Ack is a value in the response body, not a status code.

Retry Behavior

What the Tracking Outbound Message Status page grounds — Setup, Quick Find Outbound Messages, then View Message Delivery Status:

Note what Retry actually does: it moves Next Attempt forward, nothing more. Whether that also extends the overall delivery window is a separate claim, and it is the one below that is not grounded.

UNVERIFIED (2026-09-05): the backoff cadence, the 24-hour window, and the claim that a manual retry resets that window are not stated in the SOAP API Developer Guide's outbound messaging chapter, and a grep for "outbound" across the Salesforce App Limits Cheat Sheet returns one unrelated hit (change-set file counts). Treat the shape as correct and re-confirm the numbers against Salesforce Help before writing them into an SLA. What is grounded as the durability lever: useDeadLetterQueue exists for when "normal delivery fails" (api_meta.txt L140368–140371).

Outbound Message delivery retries follow an exponential backoff pattern up to 24 hours from the first failed delivery:

• Retries occur approximately at: 1 min, 2 min, 4 min, 8 min, 16 min, 32 min, and then hourly.
• After 24 hours, if acknowledgment has not been received, the message is permanently dropped — there is no automatic replay.
• Failed messages are visible in Setup > Process Automation > Outbound Messages (Pending Messages tab).
• Failed messages can be manually requeued from the Outbound Messages setup page, resetting the 24-hour window.

Field Selection Limitations

Outbound Message payloads include:

• OrganizationId, ActionId, EnterpriseUrl and PartnerUrl on every message — see the envelope table above. ActionId is "the workflow rule (action) that triggers the message", which is what lets a listener that serves several outbound messages tell them apart.
• SessionId, but only when includeSessionId is true — the element is nillable="true" and the guide calls it "Optional". It "represents the user defined in the previous step and not the user who triggered the workflow" (Defining Outbound Messaging).
• The record ID of the triggering record.
• Selected fields from the object (chosen when configuring the Outbound Message action).
• Formula fields and related object fields (via cross-object formula fields on the object) can be included.

Limitations:

• Binary fields (file attachments) cannot be included.
• Related records cannot be directly included — only fields on the triggering object and cross-object formula fields.
• The payload is a single record at a time. Outbound Messages are not batch delivery mechanisms.

Common Patterns

Setting Up an Outbound Message for Record Change Notification

When to use: An external ERP system needs to be notified when a Salesforce Opportunity stage changes to "Closed Won."

How it works:

1. Create a Workflow Rule on the Opportunity object: "Opportunity Stage changed to Closed Won."
2. Add a Workflow Action: "New Outbound Message."
3. Configure the Outbound Message:
   • Name and unique name.
   • Endpoint URL: https://erp.example.com/salesforce-webhook/opportunity.
   • User to send as: integration user (their session ID is included in the payload).
   • Select fields: Id, Name, Amount, StageName, CloseDate, AccountId.
4. Activate the Workflow Rule.
5. Configure the ERP endpoint to parse the SOAP envelope and return the acknowledgment response.
6. Test by closing an Opportunity Won and monitoring delivery in Setup > Process Automation > Outbound Messages.

Why SOAP acknowledgment matters: The ERP's HTTP 200 with JSON body is not sufficient. The endpoint must return the SOAP acknowledgment XML. If it returns JSON, Salesforce retries the message every few minutes for 24 hours, delivering the same payload hundreds of times before dropping it.

Decision Guidance

Recommended Workflow

1. Retrieve the object's existing .workflow file before writing anything — outbound messages are not standalone metadata. There is one .workflow file per object, stored in the workflows directory (api_meta.txt L139896–139898), and it holds every alert, field update, rule, task and outbound message for that object. Run the retrieve command in references/metadata-examples.md § 6; deploying a hand-written file that omits the existing members deletes them.
2. Answer the seven questions above, then author the <outboundMessages> entry — copy the shape from references/metadata-examples.md § 1, not from the guide's own sample (which is not well-formed — gotcha 8). Set fullName, name, endpointUrl, integrationUser, apiVersion, protected, and an explicit includeSessionId; add one <fields> element per field the listener parses, including Id.
3. Wire the trigger — for a workflow rule, add a <actions> block with <type>OutboundMessage</type> and a <name> that matches the outbound message's fullName exactly (§ 2); for an approval process, add the same <action> shape under finalRejectionActions / recallActions / etc. in the .approvalProcess file (§ 4). The name resolves within the object's .workflow file — a mismatch fails the deploy.
4. Hand the listener team the acknowledgment contract — send templates/outbound-message-setup-template.md § "External Endpoint Requirements" and the apiVersion you committed in step 2, so they generate the matching WSDL. Do this before the deploy, not after the first retry storm.
5. Run the checker — python3 scripts/check_outbound_message_setup.py --manifest-dir force-app/main/default. It parses every .workflow file and fails on a non-HTTPS endpoint, a missing or Id-less field list, a missing integrationUser, a non-numeric or out-of-range apiVersion, and a rule action naming an outbound message that does not exist in the same file. It warns on includeSessionId=true and on an absent useDeadLetterQueue.
6. Deploy, then verify in both directions — deploy with the package.xml in § 5, then (a) confirm the message in Setup by entering Outbound Messages in the Quick Find box and selecting Outbound Messages (L140338–140340), and (b) re-retrieve the .workflow file and diff it against source to see what the org filled in — this is how you find the apiVersion the org actually assigned.
7. Establish the drop-window watch — a message that has not acknowledged has a bounded life (gotcha 2). Record who checks the pending queue, at what interval, and what the requeue/reconciliation step is, in templates/outbound-message-setup-template.md § Monitoring.

Review Checklist

Run through these before marking work in this area complete:

• [ ] The .workflow file was retrieved before it was edited — git diff shows only additions, no removed alerts / fieldUpdates / tasks / rules
• [ ] python3 scripts/check_outbound_message_setup.py --manifest-dir <root> exits 0
• [ ] Every checker WARN is a recorded decision, not a default: includeSessionId and useDeadLetterQueue
• [ ] <apiVersion> is explicit in the file, legal (8.0, or 18.0+ — L140329), and shared with the listener team
• [ ] Every rule <actions> <name> of type OutboundMessage matches an outboundMessages <fullName> in the same file
• [ ] If an approval process references the message, package.xml carries both Workflow and ApprovalProcess
• [ ] <triggerType> was chosen against "should a correction re-notify?", not inherited
• [ ] <fields> includes Id and every field the listener parses; the list has a named owner
• [ ] Validate-only deploy (--dry-run) passed before the real deploy
• [ ] Post-deploy round-trip diff is clean — the org did not override apiVersion
• [ ] External endpoint implements the SOAP acknowledgment response, tested in a sandbox before go-live
• [ ] Message confirmed in Setup (Quick Find Outbound Messages, L140338–140340), and a test record change observed leaving the pending list
• [ ] Pending-queue check has an owner and a cadence, or a reconciliation plan stands in for it

Salesforce-Specific Gotchas

The nine grounded failure modes live in references/gotchas.md. The three that end integrations:

1. HTTP 200 without an Ack in the response body is not an acknowledgment — notificationsResponse is a single boolean and the listener must actually return it. The external system then receives the same payload repeatedly until the delivery window closes (window length: see the Retry Behavior note).
2. A message that never acknowledges is eventually discarded with no alert — useDeadLetterQueue is the platform's own mitigation and is "only available for organizations with dead letter queue permissions turned on" (api_meta.txt L140368–140370), so most orgs need an external reconciliation instead.
3. apiVersion is invisible in Setup and can break a live listener — it is "Required", auto-set at creation, and "can only be modified by using Metadata API. It can't be modified using the Salesforce user interface" (L140327–140334). Changing it to a version that doesn't support a configured field makes messages fail "until you update your outbound message listener to consume the updated WSDL" (L140334–140337).

Output Artifacts

Reference Files

Related Skills

• integration/outbound-messages-and-callbacks — The listener side: parsing the SOAP envelope and using the session ID from includeSessionId to call back into Salesforce
• integration/outbound-webhook-from-salesforce — When the target is a JSON webhook rather than a SOAP listener
• integration/platform-events-integration — The Flow- and Apex-triggerable alternative when the trigger is not a workflow rule or approval action
• admin/approval-processes — Wiring the same outbound message as an approval action (finalRejectionActions, recallActions, api_meta.txt L23615–23641)
• admin/workflow-field-update-patterns — The other action type declared in the same .workflow file you are about to retrieve and redeploy
• admin/process-automation-selection — Choosing between workflow-rule outbound messages, Flow, and Apex before any of this is built
• integration/oauth-flows-and-connected-apps — When the listener calls back with OAuth instead of the included session ID
• admin/remote-site-settings — Not required for outbound messages; Salesforce is the sender, not the caller

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/outbound-message-setup-template.md
• scripts/check_outbound_message_setup.py