81 lines
3.8 KiB
Markdown
81 lines
3.8 KiB
Markdown
|
# 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)
|