Scope
POST /webhooks/stripe — signature-verified, idempotent, drives the sponsor lifecycle and local invoice mirror.
Events
| Event |
Action |
checkout.session.completed |
create/activate Sponsor from session metadata + customer/subscription ids |
invoice.paid |
upsert SponsorInvoice (amount, hosted URL, PDF); relay branded receipt/thank-you via Brevo incl. customer-portal link |
invoice.payment_failed |
upsert invoice as failed; sponsor → PastDue |
customer.subscription.updated / deleted |
sync SponsorStatus (Active/PastDue/Cancelled) |
Rules
- Verify
Stripe-Signature against the webhook secret on the raw request body.
- Idempotent by Stripe event id — same unique-constraint-insert pattern as the GitHub webhooks (Stripe retries for days). Unhandled event types → 200 no-op.
- Rely on Stripe Invoicing natively (subscriptions generate invoices; PDFs/emails enabled in Stripe settings) — local rows exist purely for the admin dashboard.
- Brevo sends best-effort via
IEmailSender; failures never 500 the webhook (Stripe would retry and duplicate side effects — idempotency guard must cover this).
Error codes
webhooks.invalid_signature (401); everything else 200
Dependencies
Blocked by #14 and #15 (metadata contract).
Acceptance criteria
Conventions (project-wide, non-negotiable)
- .NET 9, records for immutable shapes, file-scoped namespaces, primary constructors where they read well. Minimal-API endpoints grouped per module via
IEndpointModule.MapEndpoints.
Result<T> (SharedKernel) instead of exception-driven control flow. Endpoint results map failures to ProblemDetails with the stable error codes listed above — the frontend keys off them.
- Module owns its EF Core
DbContext mapped to its own Postgres schema. Modules never reference each other's internals — cross-module needs go through a public contract interface or an in-process domain event (IEventPublisher).
- All external calls (GitHub, Stripe, Brevo, Cloudinary, Meilisearch) behind interfaces owned by the consuming module.
- Every list endpoint paginated (offset is fine). xUnit tests in
tests/CommunityPro.Tests/<Module>/ following the existing harness patterns (see Members/MembersTestHarness.cs).
Scope
POST /webhooks/stripe— signature-verified, idempotent, drives the sponsor lifecycle and local invoice mirror.Events
checkout.session.completedSponsorfrom session metadata + customer/subscription idsinvoice.paidSponsorInvoice(amount, hosted URL, PDF); relay branded receipt/thank-you via Brevo incl. customer-portal linkinvoice.payment_failedPastDuecustomer.subscription.updated/deletedSponsorStatus(Active/PastDue/Cancelled)Rules
Stripe-Signatureagainst the webhook secret on the raw request body.IEmailSender; failures never 500 the webhook (Stripe would retry and duplicate side effects — idempotency guard must cover this).Error codes
webhooks.invalid_signature(401); everything else 200Dependencies
Blocked by #14 and #15 (metadata contract).
Acceptance criteria
subscription.deletedbefore a lateinvoice.paid)Conventions (project-wide, non-negotiable)
IEndpointModule.MapEndpoints.Result<T>(SharedKernel) instead of exception-driven control flow. Endpoint results map failures to ProblemDetails with the stable error codes listed above — the frontend keys off them.DbContextmapped to its own Postgres schema. Modules never reference each other's internals — cross-module needs go through a public contract interface or an in-process domain event (IEventPublisher).tests/CommunityPro.Tests/<Module>/following the existing harness patterns (seeMembers/MembersTestHarness.cs).