BeaconRelay Production
Product documentation

BeaconRelay operating guide

Reliable, replayable and verifiable Salesforce events for applications and AI agents.

Behavior referenceProduction release
01 / Foundations

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.

ReliablePersist before delivery and recover due work.
ReplayableResume Salesforce streams and redrive Dead Letters.
VerifiableHash bodies, sign envelopes, and issue receipts.
One-way by design

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.

Application teamsReceive selected Salesforce changes through a stable HTTPS webhook contract.
Integration ownersReplace fragile listener scripts with durable events, retries, Dead Letters, and operational history.
AI agent buildersFeed agents with traceable events whose payload and delivery evidence can be inspected independently.
Audit-sensitive workflowsRetain fingerprints, signed envelopes, attempts, responses, and downloadable delivery receipts.

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.
Doing one thing well

BeaconRelay transports Salesforce events reliably, replayably, and verifiably. It is not a bidirectional synchronization engine, data-transformation platform, or Salesforce workflow builder.

Resource hierarchy

AccountCommercial owner and event allowance
StationOne authorized Salesforce org
ChannelOne Salesforce PushTopic subscription
EventOne durable Salesforce notification
ReceiverThe station's HTTPS destination

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

  1. 1
    Salesforce publishes

    The active listener receives a PushTopic message from the station's authorized org.

  2. 2
    BeaconRelay deduplicates

    The tuple station, channel, and Salesforce replay ID is unique. A repeated replay message reuses the existing event.

  3. 3
    BeaconRelay persists

    The canonical JSON payload is encrypted with authenticated encryption, fingerprinted with SHA-256, assigned pending, and committed before webhook work is queued.

  4. 4
    The delivery worker validates

    Entitlement, destination safety, payload authentication, fingerprint, and signing configuration are checked before transmission.

  5. 5
    The receiver is called

    The original canonical JSON body is sent with verification and delivery-cycle headers. Redirects are not followed.

  6. 6
    The 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.

  1. 1
    Use 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.

  2. 2
    Choose the smallest useful payload

    Select only fields the receiver needs. Confirm that object operations and filters match the business event you intend to transport.

  3. 3
    Prepare an idempotent receiver

    Accept HTTPS POST requests, return a timely 2xx response after safe acceptance, and deduplicate with X-BeaconRelay-Event-Id.

  4. 4
    Test 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.

  5. 5
    Agree 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.

Do not treat a successful HTTP response as business completion

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

BoundaryOwnerResponsibility
Salesforce sourceCustomer and SalesforceConnected-app policy, integration-user access, source records, PushTopic eligibility, and source-event availability.
Transport custodyBeaconRelayIngestion identity, encrypted persistence, retry scheduling, destination controls, attempt history, signatures, and receipts.
Payload accessCustomer accountDeciding who may reveal encrypted payloads in the authenticated workspace and handling revealed data appropriately.
HTTPS receiverCustomerAvailability, certificate validity, request verification, idempotency, timely responses, durable processing, and business outcomes.

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.