# Webhooks

Stripe webhook processing, signature verification, idempotency, and replay visibility.

Status: implemented
Version: latest
Review: source-backed

## Stripe webhook path

Stripe webhooks verify signatures unless an explicit test bypass is enabled. Processed, duplicate, and failed events are persisted for replay visibility.

| Webhook stage | Behavior | Proof |
| --- | --- | --- |
| Receive | Read event body and signature header | StripeWebhookEvent or safe error |
| Verify | Validate signature outside explicit test bypass | Accepted or rejected event |
| Idempotency | Check prior event processing | Duplicate event marked without duplicate business writes |
| Apply | Create/update customer, checkout session, order, revenue, deal | Durable business records |
| Audit | Link event to order/revenue/deal/run when available | Ledger and AuditEvent |

Checkout completion creates Customer, CheckoutSession, Order, RevenueEvent, Deal, RunEvent, and AuditEvent proof where metadata links are present.

## Operational rules

- Webhook handlers must be idempotent.
- A failed webhook should be visible and replayable.
- Test bypass must remain explicit and never be used as live proof.
- Stripe event IDs and checkout IDs are safe evidence; secrets are not.


Source paths:
- `lib/autonomous_agency_web/controllers/stripe_webhook_controller.ex`
- `lib/autonomous_agency/revenue.ex`