Use when Salesforce must POST a webhook to a third-party endpoint after a record change — with signed payloads, retries, dead-lettering, rate limits, and idempotency. Covers design choice between Outbound Message, Flow HTTP Callout, Apex Queueable callout, and Event Relay. NOT for receiving a webhook INTO Salesforce from an external system — use integration/webhook-inbound-patterns. NOT for the Workflow-triggered SOAP Outbound Message and its listener contract — use integration/outbound-messages-and-callbacks.
A webhook out of Salesforce is a callout with a delivery guarantee bolted on.
Every design decision here follows from one platform fact and one distributed-
systems fact, and teams that skip either build something that works in the
sandbox and loses events in production.
The platform fact:"You can't make a callout when there are pending
operations in the same transaction. Things that result in pending operations are
DML statements, asynchronous Apex (such as future methods and batch Apex jobs),
scheduled Apex, or sending email." A record change is a DML statement. So the
callout cannot happen in the transaction that caused it — the only question is
which async mechanism carries it.
The distributed-systems fact: the receiver can be slow, down, or lying about
success. At-least-once delivery with idempotency is the only guarantee you can
actually offer, and it has to be designed in, not added after the first incident.
HMAC over a timestamped payload, secret in an External Credential
The secret is in Custom Metadata or in code
Nothing is processed twice
An idempotency key the receiver honours
You assume exactly-once because retries look rare
You find out when it breaks
Outbox status + a DLQ depth alert
Failures are logged and nobody reads logs
Scope. This skill owns the producer side: picking the mechanism, shaping
the payload, signing it, retrying it, and knowing when it is dead. Receiving a
webhook into Salesforce is integration/webhook-inbound-patterns; verifying an
inbound signature is integration/webhook-signature-verification. The
Workflow-triggered SOAP Outbound Message and its listener WSDL contract belong to
integration/outbound-messages-and-callbacks — it appears below only as one
option in the mechanism choice.
Read standards/decision-trees/integration-pattern-selection.md (Direction 1,
Q1–Q4) before choosing. This skill implements that tree's outcome; it does not
re-derive it.
Before Starting
Establish whether the receiver is idempotent. Ask, in writing, what
happens if they receive the same event twice. If the answer is "it would
duplicate the order", the design needs an idempotency key they honour — and
agreeing that is a contract negotiation, not a code change.
Get the failure budget. "How many events may be lost, and how stale may a
delivery be?" A five-minute tolerance and a zero-loss requirement produce
completely different designs. Nobody volunteers this; you have to ask.
Classify the volume in events per minute at peak, not per day. A daily
average hides the mass update that generates 50,000 events in ninety seconds,
and that burst is what the design has to survive.
Decide who owns the secret and how it rotates. External Credential, not
Custom Metadata, not Apex source. Rotation is a Setup change if you get this
right and a deployment if you do not.
Find out whether ordering matters. If the receiver applies deltas rather
than absolute state, out-of-order delivery corrupts them — and every retrying
design reorders. The cheap fix is to send absolute state plus a version
number, and it is much cheaper to agree now.
Core Concepts
Callouts and the transaction boundary
The rule is absolute and it decides the architecture: a callout is illegal once
the transaction has pending work. A trigger has, by definition, pending DML. So
the shapes available are:
The relevant per-transaction ceilings, from the Apex Developer Guide:
Limit
Value
Callouts per transaction
100
Cumulative callout timeout per transaction
120 seconds
Default timeout per callout
10 seconds
Configurable timeout per callout
1 ms – 120,000 ms
Concurrent callouts outside the org's domain (Developer Edition)
20
The 120-second cumulative budget is the one that bites. Twelve callouts at the
10-second default exhaust it, so a Queueable that loops over deliveries needs a
bounded batch size and a per-callout timeout small enough that the batch fits.
The outbox is the design
Everything that makes this reliable — retry, backoff, dead-lettering, replay,
observability — hangs off one durable row per delivery attempt. Without it, a
retry is a loop inside a transaction that cannot outlive its own governor limits,
and a failure is a debug log nobody reads.
Webhook_Delivery__c
Idempotency_Key__c External Id, Unique ← the whole idempotency story
Status__c Pending | Sent | Failed | Dead
Attempt_Count__c
Next_Attempt_At__c ← the sweeper's index
Payload__c Long Text
Last_Status_Code__c
Last_Error__c
Write the row in the same transaction as the record change (it is DML, which is
legal there) and deliver it from a Queueable. The record change and the
intent to deliver commit or roll back together; the delivery itself is
asynchronous and retryable. That is the whole pattern.
Retry: a Finalizer, not a loop
System.Finalizer is the platform's answer to "the async job failed and I need
to react". Attach one inside a Queueable's execute, and it runs afterwards
whether or not the job threw:
System.attachFinalizer(Finalizer) — "Only one finalizer instance can be
attached to any Queueable job."
FinalizerContext.getResult() returns System.ParentJobResult — SUCCESS or
UNHANDLED_EXCEPTION — and getException() returns the exception in the
second case.
"A Queueable job that failed due to an unhandled exception can be
successively re-enqueued five times by a transaction finalizer." The counter
resets on success.
Five is a hard ceiling for finalizer-driven retry, which is exactly why long
backoff schedules belong to a scheduled sweeper reading Next_Attempt_At__c
rather than to finalizer chaining.
For the short end of the schedule, System.enqueueJob accepts a delay of 0–10
minutes and an AsyncOptions overload carrying MaximumQueueableStackDepth;
System.AsyncInfo exposes getCurrentQueueableStackDepth() and
getMaximumQueueableStackDepth() at runtime. Note the chaining constraint:
"you can add only one job from an executing job. Only one child job can exist for
each parent queueable job", and Developer Edition and Trial orgs cap the chained
stack depth at 5.
Signing
HMAC-SHA256 over "{timestamp}.{body}" is the de-facto industry shape and the
one receivers already have libraries for. Two Salesforce-specific points:
The secret belongs in a Named Credential's External Credential, referenced
from the request with the documented merge syntax
({!$Credential.<AuthProviderName>.<ParameterName>} and
{!$Credential.Password}), so that rotation is a Setup change. "Salesforce
manages all authentication for Apex callouts that specify a named credential as
the callout endpoint so that your code doesn't have to."
Sign the exact bytes you send. If you serialize once for the signature and
again for the body, key order can differ and the receiver rejects everything.
Serialize to a String once; sign that string; send that string.
The mirror-image skill for the receiving end is
integration/webhook-signature-verification — read it to know what a competent
receiver will check, because that is what you have to produce.
Mechanism comparison, with the numbers
Mechanism
Async?
Retry
Auth
Signing
Verdict
Apex Queueable + HttpClient
Yes
Yours: Finalizer + outbox sweeper
Named Credential, all protocols
Full control
Default for anything with a reliability requirement
Flow HTTP Callout
Only via Scheduled Path or async path
None built in
Named Credential (required)
Not practical declaratively
Low-volume, admin-owned, tolerant receivers
Platform Event + Apex subscriber
Yes, by construction
Subscriber-side
Named Credential
Full control
When several consumers want the same signal
Event Relay → Amazon EventBridge
Yes
AWS-side
Named Credential holding AWS account info
AWS-side
AWS-native fleets; not a way to call one HTTPS endpoint
Outbound Message (SOAP)
Yes
Platform: exponential backoff to 2 h, dropped at 24 h
Session ID / mTLS only
None
Legacy. Its host reached end of support 31 Dec 2025
Outbound Messaging's semantics are worth knowing precisely, because they are the
bar the Apex design has to clear: "A single SOAP message can include up to 100
notifications"; "If a message can't be delivered, the interval between retries
increases exponentially, up to a maximum of two hours between retries"; "messages
stay in the queue until sent successfully, or until they're 24 hours old. After
24 hours, messages are dropped from the queue"; and — the one that surprises
people — "Messages are retried independent of their order in the queue. As a
result, messages can be delivered out of order."
Event Relay is a genuinely different shape rather than a webhook alternative.
EventRelayConfig (API 56.0+, suffix .eventRelay) requires
destinationResourceName — "the developer name of the named credential, which
stores the AWS account information" — and an eventChannel. It relays platform
events and change data capture events to Amazon EventBridge. If the requirement
is "POST to a partner's HTTPS endpoint", this is the wrong tool; if it is "fan
our events into an AWS estate", it removes a whole layer of your code.
Common Patterns
Pattern A — outbox + Queueable + Finalizer
The default. Trigger writes a Webhook_Delivery__c row and enqueues; the
Queueable delivers a bounded batch; a Finalizer catches unhandled failures and
re-enqueues up to the platform's five; a scheduled sweeper picks up anything with
Next_Attempt_At__c in the past. Full implementation in
references/examples.md, Examples 1–3.
Pattern B — Platform Event as the fan-out point
When more than one consumer wants "an order closed", publish once and let
subscribers callout independently. Note the limit split: with Publish After
Commit, "Each method execution is counted as one DML statement against the Apex
DML statement limit"; with Publish Immediately, "Each method execution is
counted against a separate event publishing limit of 150 EventBus.publish()
calls". Limits.getPublishImmediateDML() reads the second.
Pattern C — Flow HTTP Callout for the low-volume, admin-owned case
Flow Builder generates an External Service registration and an invocable action
from the API's response shape, and requires an External Credential and a Named
Credential. It is a legitimate choice when volume is low, the receiver is
tolerant, and the integration should be owned by an admin — and it is the wrong
choice the moment a retry or a signature is required, because neither is
expressible declaratively.
Pattern D — notification-plus-pull
When the payload is large or sensitive, send an event that carries only an
identifier and let the receiver fetch the body over an authenticated API. This
removes payload size from your problem, removes PII from the outbox, and turns
"replay a delivery" into "they call again".
Pattern E — absolute state plus a version, never a delta
Because every retrying design reorders, {"status":"Closed","version":47} is
safe to apply twice and out of order; {"statusDelta":"+1"} is not. This is a
payload-design decision that buys you out of an entire class of production
incident, and it costs nothing at build time.
Decision Guidance
Situation
Approach
Any receiver with a reliability requirement
Outbox + Queueable + Finalizer + sweeper
Low volume, admin-owned, tolerant receiver
Flow HTTP Callout + Named Credential
Several internal consumers of the same signal
Platform Event, subscribers call out
Destination is an AWS estate
Event Relay → EventBridge
Existing Outbound Message
Migrate; its host hit end of support 31 Dec 2025
Receiver cannot deduplicate
Negotiate an idempotency key before writing code
Ordering matters to the receiver
Absolute state + version, or a single-threaded chain
Payload > a few hundred KB, or contains PII
Notification-plus-pull
Burst of 10,000+ events from a mass update
Outbox + sweeper with a bounded batch; never one Queueable per record
Receiver returns 429 with Retry-After
Honour the header; it overrides your backoff schedule
Receiver returns 4xx (not 408/429)
Dead-letter immediately; retrying a rejection wastes the budget
Secret rotation required
External Credential; the code never changes
Recommended Workflow
Route with the decision tree first. Read
standards/decision-trees/integration-pattern-selection.md, Direction 1,
Q1–Q4, and cite the branch that resolved the choice. Q4 in particular already
distinguishes transient-5xx retry, 429 throttling, idempotency keys, and
ordering sensitivity.
Design the outbox object before the sender: idempotency key as an External
Id, Unique field; status; attempt count; next-attempt timestamp; payload;
last status code and error. Everything else in this design hangs off it.
Write the delivery row in the triggering transaction and nothing else. No
callout there — the platform forbids it once DML is pending, and the failure
mode is a CalloutException in a trigger, which rolls back the user's save.
Deliver from a Queueable implementing Database.AllowsCallouts, with a
bounded batch sized against the 120-second cumulative timeout and an explicit
per-callout timeout. Use
templates/apex/HttpClient.cls —
it already carries Named Credential enforcement, timeouts, and transient
classification.
Attach a Finalizer for unhandled failures and keep the long backoff in a
scheduled sweeper. The finalizer path is capped at five successive
re-enqueues; the sweeper is not.
Sign the exact serialized string you send, with the secret in an External
Credential, and give the receiver the timestamp they need to bound replay.
Never log the payload or the signature.
Instrument the outbox, not the code path. Alert on DLQ depth and on
oldest-pending age. A dashboard of Status__c by hour answers "is it working"
without reading a single log, and a rising oldest-pending age is the earliest
signal that the receiver is degrading.
Review Checklist
No callout in any code path that runs after DML in the same transaction
Delivery intent is persisted in the triggering transaction, atomically with the change
Idempotency key is an External Id, Unique field, and is sent to the receiver
The receiver has confirmed, in writing, that they honour that key
Per-callout timeout is set explicitly, not left at the 10-second default
Retry distinguishes transient (5xx, 408, 429) from permanent (other 4xx)
Retry-After is honoured where the receiver sends it
Backoff is scheduled, not slept; no busy-wait inside a transaction
Finalizer re-enqueues are bounded, and the design knows the platform cap is five
Dead-letter state exists and is distinguishable from "still retrying"
Endpoint is callout:<NamedCredential>/...; no hostname in code
Signing secret is in an External Credential, never in Custom Metadata or source
The signed bytes and the sent bytes are the same String instance
Payload carries a schema version and a correlation id
Payload is absolute state with a version, not a delta
Nothing logs the payload, the signature, or any credential
Alerting exists on DLQ depth and on oldest-pending age
Tests use MockHttpResponseGenerator; no test touches a real endpoint
A mass-update burst has been modelled, not assumed
Salesforce-Specific Gotchas
Full detail in references/gotchas.md.
"You can't make a callout when there are pending operations" — the rule that shapes everything.
120 seconds cumulative per transaction, so twelve default-timeout callouts exhaust a Queueable.
Database.AllowsCallouts is a marker you have to remember, and forgetting it fails at runtime.
Only one finalizer per Queueable, and five successive finalizer re-enqueues.
Test.setMock plus DML ordering makes the callout-after-DML rule bite in tests too.
Platform Event publish behaviour changes which limit you consume.
A retried delivery is a reordered delivery — always, in every design.
HTTP 200 is not "processed" unless the receiver's contract says so.
Outbound Messages drop silently at 24 hours and deliver out of order by design.
Flow HTTP Callout has no retry, and adding one means leaving Flow.
Serializing twice produces two different strings and a signature the receiver rejects.
One Queueable per record does not survive a mass update.
Output Artifacts
Artifact
Description
Mechanism decision record
The chosen option, the decision-tree branch that produced it, and the volume/SLA/ordering facts behind it
Receiver contract note
Endpoint, auth, idempotency key semantics, signature scheme, what their 2xx means, and their documented rate limit
Outbox object
Webhook_Delivery__c with External Id, Unique idempotency key, status, attempt count, next-attempt time, payload, last error — plus a retention policy
Producer
Trigger or Flow writing the delivery row; Queueable with Database.AllowsCallouts delivering a bounded batch
Retry design
Backoff schedule, which status codes retry, Retry-After handling, finalizer role, and the dead-letter threshold
Named + External Credential
The endpoint and the signing secret, with a rotation runbook that requires no deployment
Payload schema
Versioned, absolute-state, with correlation id and idempotency key; documented for the receiver
Observability
Outbox status dashboard, DLQ depth alert, oldest-pending-age alert, and the replay procedure
Test suite
MockHttpResponseGenerator cases for 2xx, 5xx-then-success, 4xx-permanent, 429 with Retry-After, timeout, and a bulk burst
Related Skills
integration/webhook-signature-verification — the receiving end of the
signature you are producing; read it to know what a competent receiver checks
integration/webhook-inbound-patterns — the mirror direction, when the partner
is the one pushing to you
integration/outbound-messages-and-callbacks — the legacy SOAP Outbound
Message and its listener WSDL contract, if you are migrating one
integration/retry-and-backoff-patterns — the general backoff and
dead-lettering treatment this skill applies to webhooks specifically
integration/event-relay-configuration — Event Relay to Amazon EventBridge in
full, when the destination is an AWS estate rather than an HTTPS endpoint
apex/callout-limits-and-async-patterns — the per-transaction callout budget
and which async shape fits inside it
standards/decision-trees/integration-pattern-selection.md — Direction 1,
Q1–Q4: the routing this skill implements rather than re-derives
Related Templates
templates/apex/HttpClient.cls — Named-Credential-aware client with timeout,
transient classification, and retry already implemented
templates/apex/ApplicationLogger.cls — the queryable log this design's
observability depends on
templates/apex/tests/MockHttpResponseGenerator.cls — the only acceptable way
to test a callout
1---2name: outbound-webhook-from-salesforce3description: "Use when Salesforce must POST a webhook to a third-party endpoint after a record change — with signed payloads, retries, dead-lettering, rate limits, and idempotency. Covers design choice between Outbound Message, Flow HTTP Callout, Apex Queueable callout, and Event Relay. NOT for receiving a webhook INTO Salesforce from an external system — use integration/webhook-inbound-patterns. NOT for the Workflow-triggered SOAP Outbound Message and its listener contract — use integration/outbound-messages-and-callbacks."4category: integration5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Reliability8 - Security9 - Operational Excellence10triggers:11 - "salesforce send webhook"12 - "outbound http from salesforce"13 - "webhook retry salesforce"14 - "signed webhook hmac salesforce"15 - "flow http callout alternative"16tags:17 - integration18 - webhook19 - callout20 - outbound21 - reliability22inputs:23 - Triggering event (record change, platform event, scheduled)24 - Target endpoint + auth requirement25 - Volume and latency SLA26 - Failure tolerance + compliance requirements27outputs:28 - Webhook design (producer pattern, payload shape, signing, retry)29 - Failure handling + dead-letter30 - Observability plan31dependencies: []32version: 1.0.133author: Pranav Nagrecha34updated: 2026-08-1435metadata:36 source: https://skillmd.com/skills/pranavnagrecha/outbound-webhook-from-salesforce37---3839# Outbound Webhook From Salesforce4041A webhook out of Salesforce is a callout with a delivery guarantee bolted on.42Every design decision here follows from one platform fact and one distributed-43systems fact, and teams that skip either build something that works in the44sandbox and loses events in production.4546**The platform fact:** *"You can't make a callout when there are pending47operations in the same transaction. Things that result in pending operations are48DML statements, asynchronous Apex (such as future methods and batch Apex jobs),49scheduled Apex, or sending email."* A record change is a DML statement. So the50callout cannot happen in the transaction that caused it — the only question is51which async mechanism carries it.5253**The distributed-systems fact:** the receiver can be slow, down, or lying about54success. At-least-once delivery with idempotency is the only guarantee you can55actually offer, and it has to be designed in, not added after the first incident.5657| Concern | Established by | Fails when |58|---|---|---|59| **The event escapes the transaction** | Async boundary (Queueable, Platform Event, Scheduled Path) | The callout is attempted inline after DML |60| **Delivery survives a bad hour** | Retry with backoff + a durable outbox row | Retry is a `for` loop inside one transaction |61| **The receiver can trust it** | HMAC over a timestamped payload, secret in an External Credential | The secret is in Custom Metadata or in code |62| **Nothing is processed twice** | An idempotency key the *receiver* honours | You assume exactly-once because retries look rare |63| **You find out when it breaks** | Outbox status + a DLQ depth alert | Failures are logged and nobody reads logs |6465**Scope.** This skill owns the *producer* side: picking the mechanism, shaping66the payload, signing it, retrying it, and knowing when it is dead. Receiving a67webhook into Salesforce is `integration/webhook-inbound-patterns`; verifying an68inbound signature is `integration/webhook-signature-verification`. The69Workflow-triggered SOAP Outbound Message and its listener WSDL contract belong to70`integration/outbound-messages-and-callbacks` — it appears below only as one71option in the mechanism choice.7273Read `standards/decision-trees/integration-pattern-selection.md` (Direction 1,74Q1–Q4) before choosing. This skill implements that tree's outcome; it does not75re-derive it.7677---7879## Before Starting80811. **Establish whether the receiver is idempotent.** Ask, in writing, what82 happens if they receive the same event twice. If the answer is "it would83 duplicate the order", the design needs an idempotency key *they honour* — and84 agreeing that is a contract negotiation, not a code change.85862. **Get the failure budget.** "How many events may be lost, and how stale may a87 delivery be?" A five-minute tolerance and a zero-loss requirement produce88 completely different designs. Nobody volunteers this; you have to ask.89903. **Classify the volume in events per minute at peak**, not per day. A daily91 average hides the mass update that generates 50,000 events in ninety seconds,92 and that burst is what the design has to survive.93944. **Decide who owns the secret and how it rotates.** External Credential, not95 Custom Metadata, not Apex source. Rotation is a Setup change if you get this96 right and a deployment if you do not.97985. **Find out whether ordering matters.** If the receiver applies deltas rather99 than absolute state, out-of-order delivery corrupts them — and every retrying100 design reorders. The cheap fix is to send absolute state plus a version101 number, and it is much cheaper to agree now.102103---104105## Core Concepts106107### Callouts and the transaction boundary108109The rule is absolute and it decides the architecture: a callout is illegal once110the transaction has pending work. A trigger has, by definition, pending DML. So111the shapes available are:112113```text114Record change ──► Trigger / Flow115 │116 ├─► Queueable (Database.AllowsCallouts) ← the workhorse117 ├─► Platform Event ──► subscriber ──► callout118 └─► After-save Flow + Scheduled Path (≥ 1 min) ──► HTTP Callout action119```120121The relevant per-transaction ceilings, from the Apex Developer Guide:122123| Limit | Value |124|---|---|125| Callouts per transaction | 100 |126| Cumulative callout timeout per transaction | 120 seconds |127| Default timeout per callout | 10 seconds |128| Configurable timeout per callout | 1 ms – 120,000 ms |129| Concurrent callouts outside the org's domain (Developer Edition) | 20 |130131The 120-second cumulative budget is the one that bites. Twelve callouts at the13210-second default exhaust it, so a Queueable that loops over deliveries needs a133bounded batch size and a per-callout timeout small enough that the batch fits.134135### The outbox is the design136137Everything that makes this reliable — retry, backoff, dead-lettering, replay,138observability — hangs off one durable row per delivery attempt. Without it, a139retry is a loop inside a transaction that cannot outlive its own governor limits,140and a failure is a debug log nobody reads.141142```text143Webhook_Delivery__c144 Idempotency_Key__c External Id, Unique ← the whole idempotency story145 Status__c Pending | Sent | Failed | Dead146 Attempt_Count__c147 Next_Attempt_At__c ← the sweeper's index148 Payload__c Long Text149 Last_Status_Code__c150 Last_Error__c151```152153Write the row in the same transaction as the record change (it is DML, which is154legal there) and deliver it from a Queueable. The record change and the155*intent to deliver* commit or roll back together; the delivery itself is156asynchronous and retryable. That is the whole pattern.157158### Retry: a Finalizer, not a loop159160`System.Finalizer` is the platform's answer to "the async job failed and I need161to react". Attach one inside a Queueable's `execute`, and it runs afterwards162whether or not the job threw:163164- `System.attachFinalizer(Finalizer)` — **"Only one finalizer instance can be165 attached to any Queueable job."**166- `FinalizerContext.getResult()` returns `System.ParentJobResult` — `SUCCESS` or167 `UNHANDLED_EXCEPTION` — and `getException()` returns the exception in the168 second case.169- **"A Queueable job that failed due to an unhandled exception can be170 successively re-enqueued five times by a transaction finalizer."** The counter171 resets on success.172173Five is a hard ceiling for finalizer-driven retry, which is exactly why long174backoff schedules belong to a scheduled sweeper reading `Next_Attempt_At__c`175rather than to finalizer chaining.176177For the short end of the schedule, `System.enqueueJob` accepts a delay of 0–10178minutes and an `AsyncOptions` overload carrying `MaximumQueueableStackDepth`;179`System.AsyncInfo` exposes `getCurrentQueueableStackDepth()` and180`getMaximumQueueableStackDepth()` at runtime. Note the chaining constraint:181"you can add only one job from an executing job. Only one child job can exist for182each parent queueable job", and Developer Edition and Trial orgs cap the chained183stack depth at 5.184185### Signing186187HMAC-SHA256 over `"{timestamp}.{body}"` is the de-facto industry shape and the188one receivers already have libraries for. Two Salesforce-specific points:189190- The secret belongs in a **Named Credential's External Credential**, referenced191 from the request with the documented merge syntax192 (`{!$Credential.<AuthProviderName>.<ParameterName>}` and193 `{!$Credential.Password}`), so that rotation is a Setup change. "Salesforce194 manages all authentication for Apex callouts that specify a named credential as195 the callout endpoint so that your code doesn't have to."196- Sign the **exact bytes you send**. If you serialize once for the signature and197 again for the body, key order can differ and the receiver rejects everything.198 Serialize to a `String` once; sign that string; send that string.199200The mirror-image skill for the receiving end is201`integration/webhook-signature-verification` — read it to know what a competent202receiver will check, because that is what you have to produce.203204### Mechanism comparison, with the numbers205206| Mechanism | Async? | Retry | Auth | Signing | Verdict |207|---|---|---|---|---|---|208| **Apex Queueable + `HttpClient`** | Yes | Yours: Finalizer + outbox sweeper | Named Credential, all protocols | Full control | Default for anything with a reliability requirement |209| **Flow HTTP Callout** | Only via Scheduled Path or async path | None built in | Named Credential (required) | Not practical declaratively | Low-volume, admin-owned, tolerant receivers |210| **Platform Event + Apex subscriber** | Yes, by construction | Subscriber-side | Named Credential | Full control | When several consumers want the same signal |211| **Event Relay → Amazon EventBridge** | Yes | AWS-side | Named Credential holding AWS account info | AWS-side | AWS-native fleets; not a way to call one HTTPS endpoint |212| **Outbound Message (SOAP)** | Yes | Platform: exponential backoff to 2 h, dropped at 24 h | Session ID / mTLS only | None | Legacy. Its host reached end of support 31 Dec 2025 |213214Outbound Messaging's semantics are worth knowing precisely, because they are the215bar the Apex design has to clear: "A single SOAP message can include up to 100216notifications"; "If a message can't be delivered, the interval between retries217increases exponentially, up to a maximum of two hours between retries"; "messages218stay in the queue until sent successfully, or until they're 24 hours old. After21924 hours, messages are dropped from the queue"; and — the one that surprises220people — "Messages are retried independent of their order in the queue. As a221result, messages can be delivered out of order."222223Event Relay is a genuinely different shape rather than a webhook alternative.224`EventRelayConfig` (API 56.0+, suffix `.eventRelay`) requires225`destinationResourceName` — "the developer name of the named credential, which226stores the AWS account information" — and an `eventChannel`. It relays platform227events and change data capture events to Amazon EventBridge. If the requirement228is "POST to a partner's HTTPS endpoint", this is the wrong tool; if it is "fan229our events into an AWS estate", it removes a whole layer of your code.230231---232233## Common Patterns234235### Pattern A — outbox + Queueable + Finalizer236237The default. Trigger writes a `Webhook_Delivery__c` row and enqueues; the238Queueable delivers a bounded batch; a Finalizer catches unhandled failures and239re-enqueues up to the platform's five; a scheduled sweeper picks up anything with240`Next_Attempt_At__c` in the past. Full implementation in241[`references/examples.md`](references/examples.md), Examples 1–3.242243### Pattern B — Platform Event as the fan-out point244245When more than one consumer wants "an order closed", publish once and let246subscribers callout independently. Note the limit split: with **Publish After247Commit**, "Each method execution is counted as one DML statement against the Apex248DML statement limit"; with **Publish Immediately**, "Each method execution is249counted against a separate event publishing limit of 150 `EventBus.publish()`250calls". `Limits.getPublishImmediateDML()` reads the second.251252### Pattern C — Flow HTTP Callout for the low-volume, admin-owned case253254Flow Builder generates an External Service registration and an invocable action255from the API's response shape, and requires an External Credential and a Named256Credential. It is a legitimate choice when volume is low, the receiver is257tolerant, and the integration should be owned by an admin — and it is the wrong258choice the moment a retry or a signature is required, because neither is259expressible declaratively.260261### Pattern D — notification-plus-pull262263When the payload is large or sensitive, send an event that carries only an264identifier and let the receiver fetch the body over an authenticated API. This265removes payload size from your problem, removes PII from the outbox, and turns266"replay a delivery" into "they call again".267268### Pattern E — absolute state plus a version, never a delta269270Because every retrying design reorders, `{"status":"Closed","version":47}` is271safe to apply twice and out of order; `{"statusDelta":"+1"}` is not. This is a272payload-design decision that buys you out of an entire class of production273incident, and it costs nothing at build time.274275---276277## Decision Guidance278279| Situation | Approach |280|---|---|281| Any receiver with a reliability requirement | Outbox + Queueable + Finalizer + sweeper |282| Low volume, admin-owned, tolerant receiver | Flow HTTP Callout + Named Credential |283| Several internal consumers of the same signal | Platform Event, subscribers call out |284| Destination is an AWS estate | Event Relay → EventBridge |285| Existing Outbound Message | Migrate; its host hit end of support 31 Dec 2025 |286| Receiver cannot deduplicate | Negotiate an idempotency key before writing code |287| Ordering matters to the receiver | Absolute state + version, or a single-threaded chain |288| Payload > a few hundred KB, or contains PII | Notification-plus-pull |289| Burst of 10,000+ events from a mass update | Outbox + sweeper with a bounded batch; never one Queueable per record |290| Receiver returns 429 with `Retry-After` | Honour the header; it overrides your backoff schedule |291| Receiver returns 4xx (not 408/429) | Dead-letter immediately; retrying a rejection wastes the budget |292| Secret rotation required | External Credential; the code never changes |293294---295296## Recommended Workflow2972981. **Route with the decision tree first.** Read299 `standards/decision-trees/integration-pattern-selection.md`, Direction 1,300 Q1–Q4, and cite the branch that resolved the choice. Q4 in particular already301 distinguishes transient-5xx retry, 429 throttling, idempotency keys, and302 ordering sensitivity.3032. **Design the outbox object before the sender**: idempotency key as an External304 Id, Unique field; status; attempt count; next-attempt timestamp; payload;305 last status code and error. Everything else in this design hangs off it.3063. **Write the delivery row in the triggering transaction and nothing else.** No307 callout there — the platform forbids it once DML is pending, and the failure308 mode is a `CalloutException` in a trigger, which rolls back the user's save.3094. **Deliver from a Queueable implementing `Database.AllowsCallouts`**, with a310 bounded batch sized against the 120-second cumulative timeout and an explicit311 per-callout timeout. Use312 [`templates/apex/HttpClient.cls`](../../../templates/apex/HttpClient.cls) —313 it already carries Named Credential enforcement, timeouts, and transient314 classification.3155. **Attach a `Finalizer` for unhandled failures** and keep the long backoff in a316 scheduled sweeper. The finalizer path is capped at five successive317 re-enqueues; the sweeper is not.3186. **Sign the exact serialized string you send**, with the secret in an External319 Credential, and give the receiver the timestamp they need to bound replay.320 Never log the payload or the signature.3217. **Instrument the outbox, not the code path.** Alert on DLQ depth and on322 oldest-pending age. A dashboard of `Status__c` by hour answers "is it working"323 without reading a single log, and a rising oldest-pending age is the earliest324 signal that the receiver is degrading.325326---327328## Review Checklist329330- [ ] No callout in any code path that runs after DML in the same transaction331- [ ] Delivery intent is persisted in the triggering transaction, atomically with the change332- [ ] Idempotency key is an External Id, Unique field, and is sent to the receiver333- [ ] The receiver has confirmed, in writing, that they honour that key334- [ ] Queueable implements `Database.AllowsCallouts`335- [ ] Batch size × per-callout timeout fits inside the 120-second cumulative budget336- [ ] Per-callout timeout is set explicitly, not left at the 10-second default337- [ ] Retry distinguishes transient (5xx, 408, 429) from permanent (other 4xx)338- [ ] `Retry-After` is honoured where the receiver sends it339- [ ] Backoff is scheduled, not slept; no busy-wait inside a transaction340- [ ] Finalizer re-enqueues are bounded, and the design knows the platform cap is five341- [ ] Dead-letter state exists and is distinguishable from "still retrying"342- [ ] Endpoint is `callout:<NamedCredential>/...`; no hostname in code343- [ ] Signing secret is in an External Credential, never in Custom Metadata or source344- [ ] The signed bytes and the sent bytes are the same `String` instance345- [ ] Payload carries a schema version and a correlation id346- [ ] Payload is absolute state with a version, not a delta347- [ ] Nothing logs the payload, the signature, or any credential348- [ ] Alerting exists on DLQ depth **and** on oldest-pending age349- [ ] Tests use `MockHttpResponseGenerator`; no test touches a real endpoint350- [ ] A mass-update burst has been modelled, not assumed351352---353354## Salesforce-Specific Gotchas355356Full detail in [`references/gotchas.md`](references/gotchas.md).3573581. **"You can't make a callout when there are pending operations"** — the rule that shapes everything.3592. **120 seconds cumulative per transaction**, so twelve default-timeout callouts exhaust a Queueable.3603. **`Database.AllowsCallouts` is a marker you have to remember**, and forgetting it fails at runtime.3614. **Only one finalizer per Queueable**, and five successive finalizer re-enqueues.3625. **`Test.setMock` plus DML ordering** makes the callout-after-DML rule bite in tests too.3636. **Platform Event publish behaviour changes which limit you consume.**3647. **A retried delivery is a reordered delivery** — always, in every design.3658. **HTTP 200 is not "processed"** unless the receiver's contract says so.3669. **Outbound Messages drop silently at 24 hours** and deliver out of order by design.36710. **Flow HTTP Callout has no retry**, and adding one means leaving Flow.36811. **Serializing twice produces two different strings** and a signature the receiver rejects.36912. **One Queueable per record does not survive a mass update.**370371---372373## Output Artifacts374375| Artifact | Description |376|---|---|377| Mechanism decision record | The chosen option, the decision-tree branch that produced it, and the volume/SLA/ordering facts behind it |378| Receiver contract note | Endpoint, auth, idempotency key semantics, signature scheme, what their 2xx means, and their documented rate limit |379| Outbox object | `Webhook_Delivery__c` with External Id, Unique idempotency key, status, attempt count, next-attempt time, payload, last error — plus a retention policy |380| Producer | Trigger or Flow writing the delivery row; Queueable with `Database.AllowsCallouts` delivering a bounded batch |381| Retry design | Backoff schedule, which status codes retry, `Retry-After` handling, finalizer role, and the dead-letter threshold |382| Named + External Credential | The endpoint and the signing secret, with a rotation runbook that requires no deployment |383| Payload schema | Versioned, absolute-state, with correlation id and idempotency key; documented for the receiver |384| Observability | Outbox status dashboard, DLQ depth alert, oldest-pending-age alert, and the replay procedure |385| Test suite | `MockHttpResponseGenerator` cases for 2xx, 5xx-then-success, 4xx-permanent, 429 with `Retry-After`, timeout, and a bulk burst |386387---388389## Related Skills390391- `integration/webhook-signature-verification` — the receiving end of the392 signature you are producing; read it to know what a competent receiver checks393- `integration/webhook-inbound-patterns` — the mirror direction, when the partner394 is the one pushing to you395- `integration/outbound-messages-and-callbacks` — the legacy SOAP Outbound396 Message and its listener WSDL contract, if you are migrating one397- `integration/retry-and-backoff-patterns` — the general backoff and398 dead-lettering treatment this skill applies to webhooks specifically399- `integration/event-relay-configuration` — Event Relay to Amazon EventBridge in400 full, when the destination is an AWS estate rather than an HTTPS endpoint401- `apex/callout-limits-and-async-patterns` — the per-transaction callout budget402 and which async shape fits inside it403- `standards/decision-trees/integration-pattern-selection.md` — Direction 1,404 Q1–Q4: the routing this skill implements rather than re-derives405406## Related Templates407408- `templates/apex/HttpClient.cls` — Named-Credential-aware client with timeout,409 transient classification, and retry already implemented410- `templates/apex/ApplicationLogger.cls` — the queryable log this design's411 observability depends on412- `templates/apex/tests/MockHttpResponseGenerator.cls` — the only acceptable way413 to test a callout
Run npx get-skill add pranavnagrecha/outbound-webhook-from-salesforce in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when Salesforce must POST a webhook to a third-party endpoint after a record change — with signed payloads, retries, dead-lettering, rate limits, and idempotency. Covers design choice between Outbound Message, Flow HTTP Callout, Apex Queueable callout, and Event Relay. NOT for receiving a webhook INTO Salesforce from an external system — use integration/webhook-inbound-patterns. NOT for the Workflow-triggered SOAP Outbound Message and its listener contract — use integration/outbound-messages-and-callbacks. It is listed under Integrations & APIs on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts, makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
PranavNagrecha (@pranavnagrecha) published this skill. Their other Agent Skills are listed on their SkillMD profile.