ADR-001: Platform Events over Webhooks

Date: 2025-01-15 Status: Accepted

Context

The Customer Portal needs to trigger order provisioning when orders are approved in Salesforce. Two main approaches exist:

Inbound webhooks: Salesforce calls a BFF endpoint when order status changes
Platform Events: BFF subscribes to Salesforce Platform Events and reacts to published events

Decision

Use Salesforce Platform Events for order provisioning triggers instead of inbound webhooks.

The BFF subscribes to OrderProvisionRequested__e Platform Events. When an operator approves an order in Salesforce, a Record-Triggered Flow publishes this event, and the BFF subscriber enqueues a provisioning job.

Rationale

Why Platform Events?

No public endpoint exposure: Webhooks require exposing a public endpoint that accepts requests from Salesforce. This creates attack surface and requires:
- IP allowlisting of Salesforce egress ranges
- Request signature validation
- CSRF protection
- Rate limiting
Pull vs Push model: Platform Events use a pull model where BFF controls when to fetch events. This provides better:
- Backpressure handling
- Retry control
- Rate management
Reliability: Salesforce Platform Events have built-in replay capability. If the BFF is down, events are retained and can be replayed when it comes back up.
Simpler security: The BFF authenticates to Salesforce (outbound) rather than validating inbound requests.

Alternatives Considered

Approach	Pros	Cons
Webhooks	Immediate notification, simpler Salesforce setup	Public endpoint, security complexity, no replay
Polling	No endpoint needed, simple	Latency, wasted API calls, inefficient
Platform Events	Secure, reliable, replay support	Requires SF Platform Events license, slightly more complex subscription

Consequences

Positive

No public endpoints for external systems to call
Built-in event replay for reliability
BFF controls processing rate
Simpler security model (no signature validation)

Negative

Requires Salesforce Platform Events feature (licensing)
Slightly more complex initial setup
Events may have delivery delay vs synchronous webhooks

Implementation

┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Salesforce │    │ Platform Event   │    │     BFF         │
│  (Approval) │───▶│ OrderProvision   │◀───│  (Subscriber)   │
│             │    │ Requested__e     │    │                 │
└─────────────┘    └──────────────────┘    └────────┬────────┘
                                                    │
                                           ┌────────▼────────┐
                                           │   BullMQ Job    │
                                           │  (Provisioning) │
                                           └─────────────────┘

3.8 KiB Raw Blame History