# 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:

1. **Inbound webhooks**: Salesforce calls a BFF endpoint when order status changes
2. **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?

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

2. **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

3. **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.

4. **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) │
                                           └─────────────────┘
```

## Related

- [Platform Events Integration](../integrations/salesforce/platform-events.md)
- [Order Fulfillment](../how-it-works/order-fulfillment.md)
- [Modular Provisioning](../architecture/modular-provisioning.md)