SfSkills Domains Docs GitHub

Home / integration / event-relay-configuration

event-relay-configuration

Use when forwarding Salesforce Platform Events or Change Data Capture to AWS EventBridge via Event Relay. Covers Named Credential + Connection setup, channel selection, event filter design, replay handling. NOT for consuming external events in Salesforce (see pub-sub-api or salesforce-connect) — use integration/aws-salesforce-patterns.

Open the skill folder on GitHub

Event Relay Configuration (Salesforce → AWS EventBridge)

Event Relay is a Salesforce-managed subscriber that forwards platform events and change data capture events to Amazon EventBridge with no code and no middleware. It replaces the DIY pattern of an Apex callout from a platform event trigger, and it replaces a self-hosted Pub/Sub API consumer, by moving the subscription, the replay position, and the retry behaviour into the platform.

What it removes is operational: a process to host, a checkpoint to persist, a consumer to page someone about. What it does not remove is at-least-once delivery, unordered events, and a recovery fallback that can replay up to three days of the event bus. That work moves to the AWS side, where it belongs.

Before Starting

  1. Confirm the destination is Amazon EventBridge. Event Relay relays "platform

    events and change data capture events from Salesforce to Amazon EventBridge." For any other target, this is the wrong tool — use Pub/Sub API with your own consumer, or a Named Credential callout from Apex.

  2. Establish who owns the AWS account. Creating a relay registers a pending

    partner event source in AWS. Until an AWS administrator associates an event bus with it, nothing is delivered and Salesforce reports no error. If you cannot name that person, the integration cannot be completed.

  3. Determine whether the downstream target is idempotent. This single fact

    decides the relayOption value, and it is far cheaper to establish now than at 06:00 during a recovery.

  4. Baseline the event delivery allocation. A relay is a subscribed client and

    consumes the org's daily delivery allocation per client. Query PlatformEventUsageMetric before switching it on.

Core Concepts

Five components, in dependency order

1. The event           MyEvent__e  /  MyObject__ChangeEvent
2. Channel             MyChannel__chn                PlatformEventChannel
3. Channel member(s)   one per event, optional filter PlatformEventChannelMember
4. Credentials         ExternalCredential (AwsSv4) + NamedCredential
5. Relay               EventRelayConfig -> references (2) and (4)

A channel is a typed stream

"A channel can hold only one type of events." The valid pairs:

channelTypeeventTypeCarries
eventcustomCustom platform events (__e)
datadataChange data capture events
eventmonitoringReal-Time Event Monitoring events

Consequence: one relay per event type. An integration spanning custom events and CDC is two channels, two relays, and two partner event sources.

Filter at the channel member, not downstream

PlatformEventChannelMember.filterExpression (API 56.0 and later) is "based on SOQL and supports a subset of SOQL operators and field types" — for example City__c = 'San Francisco'. A filtered event is never delivered, so it never consumes delivery allocation. Filtering in an EventBridge rule costs you the delivery first.

The relay config is mostly immutable

<EventRelayConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <destinationResourceName>callout:AWS_Account</destinationResourceName>
    <eventChannel>Order_Events__chn</eventChannel>
    <label>Order Events Relay</label>
    <relayOption>{"ReplayRecovery":"LATEST"}</relayOption>
    <state>STOP</state>
</EventRelayConfig>

Replay recovery is a fallback, not the normal path

relayOption accepts exactly two values, {"ReplayRecovery":"LATEST"} (default) and {"ReplayRecovery":"EARLIEST"}. There is no specific-replay-id option — that is a Pub/Sub API capability, not an Event Relay one.

And it usually does not apply. On recovery the relay "attempts to resume sending events from the event bus from where it left off. In rare occasions, if it can't resume after the last relayed event, it uses the error recovery option." When it does apply, EARLIEST means everything still in the bus, up to the three-day retention — not "what you missed."

Retention

High-volume platform event messages are stored for 72 hours (3 days); legacy standard-volume messages for 24 hours. A relay paused longer than the retention window loses whatever aged out, regardless of relayOption.

State semantics

StateDeliveryPositionDiagnostics
RUNNINGYes——
PAUSEDNoPreserved (within retention)Preserved
STOPPEDNoDiscarded — only new events on resumeLastRelayedEventTime and error fields deleted
ERRORNoRetried; self-clears to RUNNING on successPopulated

During an incident, pause — never stop.

Common Patterns

Pattern A — custom platform event to EventBridge

Channel (event/custom) → member per event → AwsSv4 credential pair → relay. Full metadata in 3, Example 1.

Pattern B — CDC to EventBridge with a filter

Channel (data/data) → one member per *ChangeEvent with a filterExpression that drops the regions or record types the AWS side does not care about. This is where the allocation savings are: CDC on a busy object is the highest-volume stream most orgs have.

Pattern C — activation as a two-party runbook

Deploy in STOP, read the partner event source name from EventRelayFeedback.RemoteResource (aws.partner/salesforce.com/orgID/channelID), hand it to the AWS admin, wait for the bus association, then set RUN.

Pattern D — staleness monitoring

Poll EventRelayFeedback on a schedule and alarm on Status == 'ERROR', Status in ('STOPPED','PAUSED'), and Status == 'RUNNING' with a LastRelayedEventTime older than the stream's known cadence. Status alone misses both the self-clearing error and the wedged-but-running case. Implementation in 5, Example 4.

Decision Guidance

SituationApproach
Target is EventBridge, transformation belongs on the AWS sideEvent Relay
Target is not AWSPub/Sub API consumer, or Named Credential callout from Apex
Need in-flight enrichment, batching, or an explicit replay idPub/Sub API consumer
Low volume, high value, delivery allocation is tightApex trigger subscriber — non-API subscribers don't count against the delivery allocation
Downstream target is idempotent{"ReplayRecovery":"EARLIEST"}
Downstream target appends, notifies, or moves money{"ReplayRecovery":"LATEST"} plus a reconciliation job
Only a subset of events matter to AWSfilterExpression on the channel member
Custom events and CDC both neededTwo channels, two relays — the platform forbids mixing
  1. Confirm Event Relay fits: destination is Amazon EventBridge, no in-flight

    transformation is required, and an AWS account owner is identified and available for the handshake.

  2. Design the channel per event type, with one PlatformEventChannelMember

    per event and a filterExpression wherever the AWS side needs a subset. Remember the member full-name rule: ChannelName_EventName with double underscores collapsed to one.

  3. Create the ExternalCredential (AwsSv4) and NamedCredential, making

    sure the credential's AwsRegion parameter and the named credential's DefaultEndpoint host name the same AWS region.

  4. Deploy the EventRelayConfig in STOP, with the callout: prefix on

    destinationResourceName and the relayOption chosen against the downstream target's idempotency.

  5. Complete the AWS handshake: send the RemoteResource partner event source

    name to the AWS admin, who associates an event bus and creates a rule with a target.

  6. Set the relay to RUN and confirm delivery on both sides —

    EventRelayFeedback.LastRelayedEventTime in Salesforce, and the rule's invocation metrics in EventBridge.

  7. Wire monitoring and write the incident runbook, including the staleness

    alarm and the "pause, never stop" rule.

Review Checklist

Salesforce-Specific Gotchas

Full detail with quotes in 0.

  1. A relay cannot be created in RUN — only STOP.
  2. Creating the relay only creates a pending partner event source; without

    the AWS-side bus association, nothing flows and nothing errors.

  3. destinationResourceName needs the callout: prefix, and cannot be

    updated afterwards.

  4. One channel holds one event type, so one relay carries one type.
  5. relayOption is a rare fallback, and EARLIEST replays the whole bus.
  6. STOPPED deletes your diagnostics; PAUSED does not.
  7. RUNNING is not a health signal — ERROR self-clears and a wedged relay

    still reports RUNNING.

  8. Every relayed event consumes the daily delivery allocation, per client, and

    that allocation is shared with CDC.

  9. Deploy needs Customize Application; query needs View Setup and Configuration.
  10. The AWS credential is not in the metadata and its expiry is invisible from

    Salesforce.

  11. Region is configured twice and must agree.

Output Artifacts

ArtifactDescription
Relay metadata bundleChannel, member(s) with filters, ExternalCredential, NamedCredential, EventRelayConfig in STOP, plus the package.xml
Two-party activation runbookSalesforce steps, the partner event source name to hand over, AWS steps, and the final RUN transition, each with a named owner
Replay decision recordWhich relayOption was chosen, the downstream idempotency evidence that justified it, and the reconciliation job if LATEST
Monitoring jobScheduled EventRelayFeedback poll alarming on status and LastRelayedEventTime staleness
Allocation projectionBaseline PlatformEventUsageMetric reading and the projected delta from the new relay

Package files