Event Relays
An Event Relay is a Salesforce feature that subscribes to platform events and Change Data Capture events, then delivers them to Amazon EventBridge in AWS in near real time.
Definition
An Event Relay is a Salesforce feature that subscribes to platform events and Change Data Capture events, then delivers them to Amazon EventBridge in AWS in near real time. It removes the need for custom Apex callouts or middleware between the two clouds. Salesforce owns the subscription and the delivery, so an AWS account can consume Salesforce events the same way it consumes any native AWS event source.
An event relay is configured per event channel and tied to one AWS account through a named credential. Once it is running, every event published on that channel reaches a partner event source in EventBridge. From there, AWS rules, Lambda functions, and EventBridge Pipes route the event to wherever it needs to go. Event Relay reached general availability in October 2022 and is free to use.
How an Event Relay moves a Salesforce event into AWS
From a published event to an EventBridge bus
When a platform event or a Change Data Capture event is published in Salesforce, the running relay picks it up as a subscriber. It forwards the event to a partner event source that Salesforce registers inside Amazon EventBridge for your AWS account. The event arrives carrying its original payload and metadata, so nothing about the message is lost in transit. On the AWS side, that partner event source is associated with an event bus you choose. EventBridge rules sit on the bus and match incoming events by their fields. A matched event can trigger a Lambda function, start a Step Functions workflow, drop onto an SQS queue, or fan out to several targets at once. The key idea is that Salesforce behaves like any other EventBridge source. Your AWS team does not write a polling loop or stand up a listener service. They write the same rules and targets they would write for an S3 or DynamoDB event. That symmetry is what makes the pattern clean for serverless AWS architectures.
Platform events and Change Data Capture as the source
Event Relay works with two event types that Salesforce already produces. Platform events are custom or standard publish-subscribe messages you define, such as an Order_Placed__e event your code fires when an order is booked. Change Data Capture events are generated automatically when records of a selected object are created, updated, deleted, or undeleted. Both flow through the same relay machinery. This matters because it covers two very different integration needs from one feature. Platform events suit deliberate business signals that your Apex or Flow chooses to publish. Change Data Capture suits raw data synchronisation, where AWS needs to mirror Salesforce record changes without you writing any publishing logic. High-volume platform events are supported as well, which keeps the relay usable for busy channels rather than only light traffic. You point a relay at a channel, and whatever the channel carries is what AWS receives. Picking the right event type up front shapes the whole downstream design, so decide early whether you are relaying business intent or data state.
The named credential and the AWS trust link
An Event Relay does not hold AWS keys. It authenticates through a named credential that stores your AWS account ID and region, and it relies on an AWS Identity and Access Management role that trusts Salesforce. You create the role in your AWS account and grant it permission to write to EventBridge. Salesforce assumes that role to deliver events, using AWS Security Token Service under the hood. This trust setup is the single most common place a relay fails, because a wrong account ID, region, or role policy silently blocks delivery. The work is one time per AWS account. Several relays that target the same account can share the same named credential and role rather than each defining its own. Treating the credential as shared infrastructure keeps the configuration tidy as more channels come online. When the relay starts, Salesforce registers a partner event source in EventBridge in a pending state. You then open the AWS console, find that source, and associate it with an event bus before any events can land.
Delivery, retry, and the relay lifecycle
An Event Relay has a clear lifecycle controlled by its state. A new relay starts in a stopped state, so no events leave Salesforce until you are ready. You move it to a running state to begin delivery, and you can stop it again at any time. If the relay hits errors it cannot recover from, it can pause rather than silently drop traffic. An error recovery option, exposed through the relay configuration, governs how the relay resumes after a problem. One mode resumes from where it stopped, replaying events the channel still retains. Another mode resumes from the latest position, accepting that events during the outage are skipped. The right choice depends on whether your AWS consumer can tolerate gaps. Because the relay is a managed subscriber, you do not write retry code yourself. Salesforce handles transient delivery failures and keeps the relay position so a restart does not lose its place, within the event retention window. Outside that window, very old events age out of the channel and cannot be recovered.
Configuring a relay: Setup UI or Tooling API
There are two ways to create an Event Relay. Since the Winter '24 release, a declarative Event Relays page lives in Setup, where admins create, manage, and monitor relays without code. You select a named credential, an event channel, and an error recovery option, and the relay is created in a stopped state. The same release added support for orgs hosted on Hyperforce, widening where the feature runs. The programmatic path uses the EventRelayConfig object, available in API version 56.0 and later, through the Tooling API or Metadata API. Configuration as metadata lets you version a relay in source control and deploy it across sandboxes and production with the rest of your release. A companion object, EventRelayFeedback, surfaces the relay's runtime status and any errors so you can build monitoring around it. Most teams start in the Setup UI to prove the connection, then move the definition into metadata for repeatable deployment. Whichever path you choose, the AWS-side association of the partner event source to an event bus still happens in the AWS console.
Where Event Relay fits among Salesforce event options
Event Relay is one of several ways events leave Salesforce, and choosing well saves rework. Platform events stay inside Salesforce for subscribers built in Apex, Flow, or Lightning components. The Pub/Sub API streams those same events out over gRPC to any external client that can hold a connection and manage its own replay. Event Relay is the option to reach when the consumer lives in AWS and you would rather not run a streaming client at all. It trades the fine control of a self-managed subscriber for a fully managed delivery path into EventBridge. For a single record callout to one system, an Apex callout or an Outbound Message may still be simpler. For broad, ongoing, event-driven integration with AWS, the relay is usually the lower-maintenance answer. A worked example: a Change Data Capture event on Account flows through a relay to EventBridge, where a rule triggers a Lambda that updates an AWS data warehouse. No middleware runs, and the sync stays close to real time.
How to create an Event Relay to Amazon EventBridge
Creating an Event Relay means defining an EventRelayConfig that points a Salesforce event channel at your AWS account, then activating the partner event source in EventBridge. You can do this in the Setup UI or with the Tooling or Metadata API. The fields below describe the declarative path.
- Set up the AWS side first
In your AWS account, create an IAM role that trusts Salesforce and can write to EventBridge. Note the AWS account ID and the target region. You will reference these when you create the named credential.
- Create the named credential
In Setup, create a named credential that stores the AWS account ID and region for the relay. Several relays targeting the same account can reuse this one credential rather than each defining its own.
- Create the event relay
Open the Event Relays page in Setup. Select the named credential, the event channel to relay, and an error recovery option. Save the relay; it is created in a stopped state so nothing is delivered yet.
- Associate the partner event source in AWS
Salesforce registers a partner event source in EventBridge in a pending state. In the AWS console, find that source and associate it with the event bus you want to receive the events.
- Start the relay and verify
Change the relay state to running. Publish a test event in Salesforce and confirm it reaches the EventBridge bus, for example by attaching a simple Lambda or CloudWatch logging rule.
The credential holding your AWS account ID and region. It backs the trust link Salesforce uses to assume the IAM role and write to EventBridge.
The platform event or Change Data Capture channel whose events the relay forwards. One relay handles one channel.
Controls how the relay resumes after an error: replay retained events from where it stopped, or skip ahead to the latest position.
The run state of the relay. New relays start stopped; you move the relay to running to begin delivery and can stop it again later.
- The IAM role trust relationship is the most common failure point. A wrong account ID, region, or role policy blocks delivery silently, so verify it in a sandbox first.
- Events do not flow until you associate the partner event source with an event bus in the AWS console. Creating the relay in Salesforce alone is not enough.
- Choose the error recovery option deliberately. Resuming from the latest position skips events that occurred during an outage, which may break a data sync that expects every change.
- Events outside the channel retention window cannot be replayed. A relay stopped for too long may miss events that have already aged out of the channel.
Prefer this walkthrough as its own page? How to Event Relays in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- Event Relay (Salesforce Developers)Salesforce
- Event Integration with Amazon EventBridgeSalesforce
Straight from the source - Salesforce's reference material on Event Relays.
Hands-on resources to go deeper on Event Relays.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Where do Event Relays forward Salesforce platform events for native consumption?
Q2. Which Salesforce capability exposes platform events outside the org over gRPC streams, sitting alongside Event Relays in the same pub-sub story?
Q3. What does Salesforce take responsibility for once an Event Relay is configured?
Discussion
Loading discussion…