BeaconRelay operating guide

Salesforce OAuth setup

Each station uses a customer-managed Salesforce External Client App and OAuth authorization code flow with PKCE S256. This gives every Salesforce organization an independent authorization boundary instead of sharing one global Consumer Secret. BeaconRelay never requests or stores a Salesforce password or security token. The requested scopes are api and refresh_token.

Before you begin

• You can create or administer a Local External Client App in the Salesforce organization.
• The Salesforce user can use the API and can read the objects and fields needed by the channels.
• If the app uses admin-preapproved access, the test user has the required profile or permission set assignment.
• You have a public HTTPS receiver ready before testing event delivery.

Access tokens are refreshed using that station's encrypted credentials. Salesforce identity supplies the organization and user IDs, and one Salesforce organization can belong to only one BeaconRelay account at a time. Connecting the same org from another BeaconRelay account is rejected until its existing station is fully deleted.

Use Replace OAuth credentials in Salesforce Orgs to rotate a Consumer Key or Consumer Secret. The replacement is atomic: cancellation, an OAuth error, or authorization of the wrong Salesforce org leaves the current credentials active. Every station requires credentials from the customer's own Salesforce External Client App.

Station setup

1. 1
   Connect and verify the org

   In BeaconRelay, go to Salesforce Orgs, choose Connect Salesforce, enter a clear station name, select Production/Developer or Sandbox, and paste the Consumer Key and Consumer Secret. Continue to Salesforce, authorize the intended user, then verify the organization and integration-user identity shown by BeaconRelay. If the popup is blocked, use the same-page authorization fallback.

2. 2
   Set the receiver

   Provide one public HTTPS webhook for the station. BeaconRelay validates the URL now and again before each delivery.

3. 3
   Create a named channel

   Give the channel a meaningful name, choose a supported object, select payload fields and operations, then add optional validated filters.

4. 4
   Review the generated topic

   Confirm the object, selected fields, operations, and generated query before submitting the PushTopic to Salesforce.

5. 5
   Start the listener

   Start performs an OAuth refresh and topic-validation preflight before it queues the listener. The station is marked active only after the start request is accepted.

6. 6
   Send one controlled event

   Create or update a matching test record in Salesforce, then correlate it through Event Inbox, Delivery, and Operational Log using its EVT- identifier.

Channel rules

The channel builder produces a constrained SOQL query and creates a Salesforce PushTopic. The server validates every selection against live Salesforce describe metadata rather than trusting browser values.

• Id is always selected and is required.
• At most 50 payload fields can be selected.
• At least one of create, update, delete, or undelete must be enabled.
• Filters are joined with AND and values are type-checked and escaped.
• LIKE is limited to string-like fields; range comparisons require ordered types.
• Salesforce receives NotifyForFields: Referenced.

Objects and fields

Custom objects ending in __c are accepted when Salesforce marks them queryable and not deprecated. Standard objects are intentionally allow-listed:

Address, base64, complex, and location fields cannot be selected. Calculated fields and address, base64, complex, location, and textarea types cannot be used as filters. Salesforce metadata remains authoritative and can reject a definition that violates org-specific capabilities.

Receiver rules

Each station currently has one receiver. A destination must use HTTPS, include a resolvable public hostname, and resolve only to global addresses. Localhost, private, loopback, link-local, reserved networks, embedded credentials, and URL fragments are rejected.

Updating the receiver reroutes pending, retrying, budget-blocked, and future eligible attempts to the new URL and records the old and new routes. A request already in flight may complete against the URL it started with.

Event state machine

The recovery worker scans due pending, retry, and blocked_budget events and stale delivering leases. It excludes blocked_connection events. Database claims prevent concurrent delivery of the same event.

HTTP and network classification

HTTP 500 is retryable. HTTP 408 is retryable. HTTP 429 and 503 may influence timing through a valid Retry-After header.

Automatic retry policy

Each delivery cycle permits 12 attempts. The first attempt is immediate. After failed attempts 1 through 11, the standard base delays are:

• Each base delay receives random jitter of ±20% to prevent synchronized retry storms.
• For HTTP 429 or 503, a valid seconds or HTTP-date Retry-After is honored when longer than the jittered delay, capped at 24 hours.
• The recovery scan runs frequently, but it never intentionally sends before next_attempt_at.
• Attempt history is append-only. Global attempt numbers continue across manual redrive cycles.
• An optional accelerated profile exists for controlled testing only; staging and production behavior default to the standard profile.

Dead Letter recovery

Manual Redrive appears only for a Dead Letter in the event's Delivery tab. The dialog shows both the event's previously assigned destination and the current receiver when they differ; the new cycle always resolves and validates the current receiver on the server. Pending, Delivering, Retry, and Blocked events remain automatic and cannot be manually redriven.

1. 1
   Eligibility is checked again on the server

   The event must belong to the signed-in owner and still be a Dead Letter.

2. 2
   Safety and entitlement are checked

   The current receiver must be valid public HTTPS and the account must allow delivery. Payload-integrity failures cannot be redriven.

3. 3
   A new cycle begins

   The cycle number and redrive count increment; cycle attempts reset to zero while global attempts remain intact.

4. 4
   Automatic delivery resumes

   The current receiver is used with a fresh 12-attempt cycle and the standard retry policy.

5. 5
   Forgotten reroutes remain repairable

   The webhook editor reports active undelivered events still assigned to an older destination. Apply current destination updates those routes without changing the URL. The operation is idempotent, audited, and does not alter Delivered events or Dead Letters.

Redrive is CSRF-protected, owner-scoped, row-locked, audited, and rate-limited to five requests per event and request identity in ten minutes.

Receiver responses and attempts

Every actual request records target URL, cycle, global and cycle attempt numbers, outcome, HTTP status, error class, duration, response headers, and response body. Authorization, Proxy-Authorization, and Set-Cookie response headers are redacted. Response bodies are encrypted and limited to 64 KiB; larger bodies are marked truncated.

Encryption at rest

Event payloads and receiver response bodies are stored as authenticated AES-256-GCM envelopes. Each value receives a random data-encryption key and nonce. The data key is itself wrapped by the configured master key with separate nonce and authenticated context bound to the event or attempt identity.

Stored plaintext

The active gateway path stores payload and response plaintext columns as null.

Authentication

GCM authentication and context binding detect ciphertext, nonce, key, or identity mismatch.

Dashboard reveal

Owner-only POST, CSRF token, separate reveal token, ten reveals per minute per session, integrity recheck, no-store response, and an audit event.

Key boundary

The application worker can decrypt to deliver. This is encryption at rest, not zero-knowledge or receiver-only end-to-end encryption.

Payload integrity proof

At ingestion, BeaconRelay computes SHA-256 over the exact canonical JSON body it stores and later sends. Before every attempt and every dashboard reveal, it decrypts the payload and recomputes that fingerprint. A mismatch opens a critical integrity incident, prevents delivery, and makes the event ineligible for Redrive.

On first delivery, BeaconRelay creates a deterministic envelope containing version, event ID, station ID, channel, replay ID, received timestamp, and payload SHA-256. The envelope is canonicalized and signed with Ed25519. The event signature and envelope are retained and reused for later attempts and redrive cycles.

Webhook verification headers

Receiver verification procedure

1. 1
   Read the raw body

   Do not reserialize parsed JSON before hashing.

2. 2
   Decode the signed envelope

   Base64url-decode X-BeaconRelay-Signed-Envelope.

3. 3
   Load the trusted public key

   GET /.well-known/beaconrelay/keys/<key-id> from the configured BeaconRelay origin and pin or cache it by key ID.

4. 4
   Verify Ed25519

   Verify the signature against the exact decoded envelope bytes.

5. 5
   Verify the body

   Compare SHA-256 of the raw request body with payload_sha256 in the verified envelope.

6. 6
   Deduplicate

   Use the verified event ID as the idempotency key before committing receiver work.

Signed delivery receipts

Each signed attempt can produce a downloadable receipt containing receipt and event IDs, event signature, payload and response hashes, target URL hash, outcome, HTTP status, timestamps, global attempt number, delivery cycle, and cycle attempt number. BeaconRelay signs the canonical receipt with Ed25519.

Listener lifecycle

Each running station has a generation token and one Redis-backed listener lease. A listener must own the current generation to process messages. Starting a newer generation supersedes old work. An intentional user stop invalidates health state and is never automatically reversed by the watchdog.

OAuth access is refreshed from the encrypted refresh token as needed. Successful Salesforce /meta/connect responses update the connection heartbeat; task liveness is tracked separately.

Every manual start first validates or refreshes OAuth and then checks the configured Salesforce topics. Invalid authorization requests reconnection; an unavailable Salesforce API or invalid topic prevents startup with a visible warning. These failures do not mark the station active and must not produce an internal-server-error page.

Organization lifecycle

Remote cleanup failure cannot block secure local erasure. BeaconRelay reports that warning because it cannot prove Salesforce-side PushTopic removal or token revocation after access has already failed. In that case, an administrator should inspect the External Client App OAuth usage and PushTopics in Salesforce.

Lifecycle test runbook

Run this sequence with a test Salesforce org. Record the station name, Salesforce org ID, receiver URL, channel count, and a known EVT- identifier before each destructive step so every state transition can be checked.

1. 1
   Establish the baseline

   Connect the org, configure one receiver and one named channel, start the listener, generate a matching Salesforce event, and verify one accepted delivery in Event Inbox and Operational Log.

2. 2
   Test intentional Stop and Start

   Stop the station and wait beyond the watchdog interval; it must remain stopped. Start it again. The start preflight must complete without deleting configuration or changing the replay position.

3. 3
   Test failed credential replacement

   Open Replace OAuth credentials and cancel it, then repeat with an invalid credential or the wrong Salesforce org. The original station authorization must remain active and usable.

4. 4
   Test successful credential replacement

   Authorize replacement credentials for the same Salesforce org. Start the station and send another event. Delivery should continue through the same station, channel, receiver, and event history.

5. 5
   Test Disconnect

   Disconnect the org. Confirm the listener is stopped, reconnect requires a fresh Consumer Key and Consumer Secret, preserved channels and history remain visible, and eligible pending deliveries show a connection-blocked state.

6. 6
   Test ownership isolation

   While disconnected, try connecting the same Salesforce org from a second BeaconRelay account. It must be rejected because Disconnect preserves ownership.

7. 7
   Test Reconnect

   From the original account, enter fresh credentials and authorize the same org. A different org must be rejected. After the correct authorization, confirm blocked events return to Pending, start the listener, and deliver a new event.

8. 8
   Test Delete last

   Stop the station, choose Delete, and enter the exact station name. Confirm its receiver, channels, events, attempts, replay data, monitoring, incidents, credentials, and encrypted payloads disappear. The same Salesforce org should then be connectable by another BeaconRelay account.

Pass criteria

• No lifecycle failure exposes a Consumer Key, Consumer Secret, access token, refresh token, or decrypted payload.
• Stop never becomes an automatic watchdog restart; Disconnect never silently behaves like Delete.
• Cancelled and failed credential replacement never overwrite the working authorization.
• Reconnect accepts only the station's original Salesforce org and resumes connection-blocked events.
• Only full Delete releases the Salesforce org for another BeaconRelay account.
• Event Inbox and Operational Log correlate test deliveries with the same EVT- identifier.

Replay and deduplication

Replay markers are persisted in the database and mirrored in Redis. On reconnect, the durable database marker is preferred and repopulates Redis. Without a marker, the subscription begins with new events. Salesforce ultimately controls how long replay IDs remain available.

The database uniqueness rule on station, channel, and replay ID is the authoritative ingestion deduplication barrier. A short-lived Redis delivered marker supplements listener behavior but is not the source of truth.

Watchdog recovery

The watchdog evaluates stations marked alive and not intentionally stopped. Healthy recovery resolves listener incidents. Unhealthy listeners are restarted locally through generation invalidation, task revocation, and a fresh listener task. Dashboard-initiated successful restarts are informational; watchdog restarts are warnings because they indicate detected service degradation.

Monitoring and incident lifecycle

Monitoring events are an append-only operational timeline. Incidents are the actionable state derived from those events: Active, Acknowledged, or Resolved. Acknowledgement records human awareness but does not resolve the condition.

Possible-loop warnings are observational: by default, ten events for one record and channel within 60 seconds produce one warning, with a five-minute warning cooldown. Events are not discarded.

Application security controls

• Owner-scoped database queries protect stations, events, receipts, and payload reveal.
• Mutating browser operations use POST and CSRF protection.
• Secure, HttpOnly, SameSite=Lax session cookies use a sliding 45-minute idle lifetime.
• HSTS, frame denial, content sniffing prevention, referrer policy, permissions policy, and no-store responses protect browser surfaces.
• Login, verification, resend, password reset, payload reveal, and Redrive paths are rate-limited.
• Stripe webhook events are persisted and processed idempotently; email delivery has its own durable retry path.

Plan allowances

Enterprise limits are contracted rather than advertised as unlimited. The baseline shown above starts at 5 million unique events per month and 90 days of payload retention.

Capabilities included on every plan

Durable ingestion

The encrypted event is committed before the first webhook request is queued.

Delivery recovery

Every plan receives the 12-attempt retry cycle, local due-work recovery, receiver rerouting, and manual Dead Letter redrive.

Operational evidence

Event states, attempts, receiver responses, incidents, route history, replay identity, hashes, signatures, and signed receipts remain available according to their applicable retention rules.

Security

Salesforce OAuth, HTTPS destination validation, encrypted payloads and responses, CSRF protection, owner scoping, rate limits, and audited payload reveal are not premium add-ons.

Event accounting

Only a newly persisted unique Salesforce event consumes allowance. Duplicate replay messages, retries, and manual redrives do not consume another unit.

Event accounting

A unique Salesforce event consumes one unit when its encrypted payload and identity become durable in BeaconRelay. The station, channel and Salesforce replay ID form the deduplication key, so replayed copies do not consume a second unit. Automatic attempts, retries and manual Dead Letter redrives are free. When allowance reaches zero, newly received events remain durable as Blocked and are reconsidered after entitlement restoration instead of being silently discarded.

Trial lifecycle

The Trial lasts 14 days from account creation and includes 2,500 unique events. Lifecycle enforcement stops active listeners, invalidates listener health state, marks the station entitlement-blocked, and moves pending or retrying events to Blocked. It emits a persisted trial-expired monitoring event and incident.

Monthly renewal

Stripe webhook events are persisted before lifecycle application. A new paid invoice replenishes the plan allowance once, identified by invoice ID, updates the billing period, clears entitlement blocks, and queues the subscription email. Duplicate delivery of the same Stripe event or invoice does not reset the allowance twice.

An account owner can schedule cancellation from Account and plans. BeaconRelay verifies that the Stripe subscription belongs to the signed-in customer and requests cancellation at period end, so paid limits remain active through the displayed date. Stripe's signed subscription update confirms the schedule. When Stripe sends the final subscription-deleted event, the paid allowance becomes unavailable and the existing lifecycle worker stops listeners and blocks pending delivery. Operational evidence remains subject to its normal retention policy.

Payload retention

Retention applies to encrypted event payloads and encrypted receiver response bodies. Cleanup erases content only after an event reaches Delivered or Dead Letter; pending, retrying and blocked events keep the payload required for delivery. Expiry does not remove the event identity, SHA-256 fingerprint, signature, signed receipts, attempt metadata, route history or incident history. An expired Dead Letter cannot be redriven because its body no longer exists.

Operational limits and guarantees

Webhook request

HTTPS only, 5-second connect timeout, 30-second read timeout, no redirects.

Response capture

64 KiB maximum, encrypted at rest, with credential and cookie headers redacted.

Delivery cycle

12 attempts, including the immediate attempt; Dead Letter afterward.

Redrive

Dead Letter only, five requests per ten minutes per event/request identity, current receiver, new cycle.

Payload reveal

Owner only, ten requests per minute per browser session, fully audited.

Batch recovery

Up to 50 due gateway events per recovery task invocation.

Delivery model

Durable and at-least-once under ambiguous network outcomes; receiver idempotency is required.