feat: Event-driven webhook delivery for customer integrations

[dkirby-ms]

Summary

Add an event-driven webhook delivery system that lets customers register HTTP endpoints and receive signed event payloads when things happen in their SaaS subscription. Uses Azure Service Bus for reliable delivery and an Azure Function for processing/retries.

Includes a demo webhook receiver (Azure Function) that customers/publishers can deploy to test the full loop end-to-end.

Why

Customers building on top of FastSaaS need to react to events in their own systems — syncing with identity providers, triggering internal workflows, feeding BI pipelines, alerting their teams. Webhooks are the standard integration pattern (Stripe, GitHub, Twilio).

Event Types

Subscription lifecycle

• subscription.activated — new subscription goes live
• subscription.suspended — subscription paused
• subscription.canceled — subscription ended
• subscription.renewed — billing cycle renewed
• plan.changed — customer changed plans

Seat/member changes

• member.added — new member joined the tenant
• member.removed — member removed from tenant
• seat.limit.approaching — approaching seat cap (e.g., 80%)

Usage/metering

• usage.threshold.reached — usage hit a configured threshold
• usage.reported — metering event was recorded

Architecture

1. Event producers — API services publish events to Azure Service Bus topics when actions occur (subscription changes, member updates, metering thresholds)
2. Service Bus — Reliable message broker with per-tenant subscriptions and dead-letter support
3. Azure Function — Processes messages from Service Bus, delivers HTTP POST to customer-configured endpoints with:
   • HMAC-SHA256 signed payloads (shared secret per webhook)
   • Retry with exponential backoff (3 attempts)
   • Dead-letter after exhausted retries
4. Webhook registry — Database table storing customer webhook configurations (URL, secret, subscribed event types, active/inactive)
5. Delivery log — Track delivery attempts, status codes, failures per webhook

Customer Portal UI

The existing Webhooks page in the customer sidebar gets wired up:

• Register/edit/delete webhook endpoints
• Select which event types to subscribe to
• View delivery history (timestamp, event type, status code, success/failure)
• Test button to send a sample payload
• Rotate webhook signing secret

Publisher Portal UI

• View cross-tenant webhook delivery health (success rate, failure rate)
• See dead-lettered events

Demo Webhook Receiver

A ready-to-deploy Azure Function that acts as a sample webhook consumer for documentation and testing:

• HTTP-triggered Azure Function that receives webhook payloads
• Validates the HMAC-SHA256 signature against a configured secret
• Logs received events to Application Insights / console
• Returns the parsed event details in the response (for easy verification)
• Deployable via Bicep alongside the main infrastructure
• Documentation walkthrough: step-by-step guide to deploy the receiver, register it in the portal, trigger events (e.g., add a member), and see the payload arrive
• Can also serve as a template for customers building their own webhook consumers

Infrastructure

• Bicep templates for Service Bus namespace + topics + subscriptions
• Azure Function App for webhook delivery processor
• Azure Function App for demo webhook receiver
• Database migration for webhook_endpoints and webhook_delivery_log tables

Acceptance Criteria

• Customers can register webhook URLs and select event types in the portal
• Subscription lifecycle events trigger webhook deliveries
• Payloads are HMAC-SHA256 signed with a per-webhook secret
• Failed deliveries retry with exponential backoff
• Delivery history is visible in the customer portal
• Test button sends a sample event to verify the endpoint
• Demo webhook receiver validates signatures and logs events
• Documentation includes end-to-end walkthrough using the demo receiver
• Service Bus + Function Apps provisioned via Bicep
• README documents setup, event catalog, payload format, and demo walkthrough