Product contract
BeaconRelay is a one-way transport layer from Salesforce Streaming API PushTopics to one HTTPS webhook receiver per connected Salesforce organization. It receives an event, persists it before outbound delivery, retries transient failures locally, records every attempt, and provides cryptographic evidence that the delivered body matches the event BeaconRelay stored.
BeaconRelay does not write records back to Salesforce. High activity on one record is observed and warned about, but transport does not perform CRUD operations or suppress valid Salesforce events.
When BeaconRelay is a good fit
BeaconRelay is for teams that need Salesforce record changes delivered to an application, service, automation, or AI agent without building and operating Apex transport code. It is most valuable when delivery must remain understandable after failures, restarts, credential changes, and receiver outages.
A focused transport layer
- Use BeaconRelay when Salesforce is the event source and one HTTPS receiver per station is the destination.
- Keep transformations and business decisions in the receiving application, where they can be versioned and tested with domain logic.
- Design the receiver to be idempotent because a webhook can be delivered more than once after network ambiguity.
BeaconRelay transports Salesforce events reliably, replayably, and verifiably. It is not a bidirectional synchronization engine, data-transformation platform, or Salesforce workflow builder.
Resource hierarchy
A station is the boundary for Salesforce identity, channels, listener health, replay cursors, monitoring, receiver routing, and events. Events never exist independently of a station and owner.
Core terminology
- Station
- The isolated operating boundary for one authorized Salesforce organization, its receiver, channels, replay position, events, and monitoring.
- Channel
- A named BeaconRelay subscription backed by one Salesforce PushTopic definition for a selected object, fields, operations, and optional filters.
- Event ID
- The stable BeaconRelay identifier shown as
EVT-.... Use it to correlate Event Inbox, attempts, incidents, headers, receipts, and support requests. - Replay ID
- The Salesforce stream position used for ingestion deduplication and resuming a channel when Salesforce still retains that position.
- Delivery attempt
- One recorded HTTPS request and its observed outcome, including timing, status, safe response metadata, and response-body evidence.
- Delivery cycle
- The initial automatic delivery sequence or a later manual Redrive sequence. Attempt numbers remain globally traceable across cycles.
- Dead Letter
- A durable event whose automatic retry schedule has ended or whose failure is not automatically retryable. It remains available for inspection and eligible manual Redrive.
- Receipt
- A signed statement of the event and delivery result observed by BeaconRelay. It does not assert that the receiver committed business work.
- Incident
- An actionable operational condition derived from monitoring events and tracked as Active, Acknowledged, or Resolved.
Event path
- 1Salesforce publishes
The active listener receives a PushTopic message from the station's authorized org.
- 2BeaconRelay deduplicates
The tuple station, channel, and Salesforce replay ID is unique. A repeated replay message reuses the existing event.
- 3BeaconRelay persists
The canonical JSON payload is encrypted with authenticated encryption, fingerprinted with SHA-256, assigned
pending, and committed before webhook work is queued. - 4The delivery worker validates
Entitlement, destination safety, payload authentication, fingerprint, and signing configuration are checked before transmission.
- 5The receiver is called
The original canonical JSON body is sent with verification and delivery-cycle headers. Redirects are not followed.
- 6The outcome is recorded
Status, latency, safe response headers, an encrypted bounded response body, signature receipt, retry schedule, and incident effects are persisted.
Before the first live event
A reliable transport starts with explicit ownership on both sides of the webhook. Complete this checklist before relying on a station for production changes.
- 1Use a controlled Salesforce identity
Authorize with a dedicated integration user where possible and grant only the object, field, and API permissions required by the planned channels.
- 2Choose the smallest useful payload
Select only fields the receiver needs. Confirm that object operations and filters match the business event you intend to transport.
- 3Prepare an idempotent receiver
Accept HTTPS POST requests, return a timely 2xx response after safe acceptance, and deduplicate with
X-BeaconRelay-Event-Id. - 4Test one known record change
Trigger a controlled Salesforce change and follow the same
EVT-identifier through Event Inbox, Delivery, Response, Operational Log, and the receiving application. - 5Agree on recovery ownership
Decide who investigates Salesforce authorization, who owns the receiver, who may reveal encrypted payloads, and who may manually Redrive a Dead Letter.
A 2xx response means the receiver accepted the request. The receiving system remains responsible for durable processing, idempotency, and any downstream business transaction.
Delivery semantics
- Durability
- Database persistence precedes outbound webhook delivery. A broker failure leaves the event due for the local recovery worker.
- Ordering
- Events retain Salesforce replay identity and receive time, but strict receiver-side ordering is not promised across retries or concurrent channels.
- Duplicates
- BeaconRelay suppresses duplicate Salesforce replay IDs, but network ambiguity can still produce receiver duplicates. Consumers should deduplicate with
X-BeaconRelay-Event-Id. - Acceptance
- Any HTTP status from 200 through 299 is accepted. A response body is not required.
- Exactly once
- Not claimed. No webhook transport can prove that a receiver committed work when its successful response is lost.
Trust boundaries
Salesforce authenticates the connected user and emits the source event. BeaconRelay controls persistence, scheduling, encryption at rest, signatures, and the outbound request. The customer controls the receiver. A BeaconRelay receipt proves what BeaconRelay observed; it is not a Salesforce signature and not proof that the receiver committed a database transaction.
Shared responsibility model
Use the EVT- identifier as the common reference when responsibility crosses a boundary. It connects what BeaconRelay received, what it attempted, what the receiver returned, and what operators later investigated.