## Why webhook-first

External providers (Stripe) are source-of-truth for critical events. Beacon prioritizes fast ingestion and minimal-entry validation to avoid timeouts and event loss.

## Processing flow

<Steps>
  <Step title="1) Ingestion">Receive webhook, validate signature, and persist event.</Step>
  <Step title="2) Fast ack">Return `2xx` as soon as event is safely persisted.</Step>
  <Step title="3) Async execution">Run business logic in workers with controlled retries.</Step>
  <Step title="4) Observability">Publish final state and queue/latency/failure metrics.</Step>
</Steps>

## Operational guarantees

- Deduplication by `event.id` for provider re-delivery.
- Safe reprocessing through business idempotency rules.
- Failure isolation by event type and organization.

## Minimum metrics

| Metric | Objective |
| --- | --- |
| Webhook ack latency | keep low and stable |
| Queue depth | detect backlog early |
| Retry rate | catch downstream degradation |
| Time to final state | measure operational impact |

<Tip title="Benefit">This model reduces provider timeout risk and improves replay/recovery predictability.</Tip>