Webhook & Event-Driven Architecture for SaaS

Webhooks implement a "push" model: when a triggering event occurs in the SaaS product (a new ticket is created, a subscription renews, a user's account status changes), the product makes an HTTP POST request to a URL configured by the customer, delivering the event payload in real time. Polling (the alternative) involves the customer's system making periodic GET requests to the API to check whether anything has changed — checking every 5 minutes means events can be up to 5 minutes late, and the constant polling creates unnecessary API load regardless of whether events are occurring. Webhook advantages: real-time delivery (event notification within milliseconds of the triggering action); zero polling overhead (no wasted API calls in periods of inactivity); lower API rate limit consumption (webhook events don't count against request quotas); and simpler integration code (the customer writes a handler function rather than a polling loop with state management). Webhook limitations: the customer must run a public HTTPS endpoint to receive events (infrastructure requirement); event delivery can fail if the receiving endpoint is down (requiring a robust retry mechanism from the provider); and ordering guarantees are typically not provided (events may arrive slightly out of order under high load). Well-designed webhook infrastructure addresses these limitations through retry with exponential backoff, event ordering metadata (sequence numbers or timestamps), and a webhook log accessible through the dashboard for debugging missed events.

Webhook reliability is measured by delivery rate — the percentage of generated events that are successfully delivered to customer endpoints. Sub-99% delivery rates make webhooks unreliable for production integrations. Reliability engineering requirements: Delivery retry with exponential backoff: if the customer endpoint returns a non-2XX response or times out, the provider retries delivery with increasing intervals (retry at 1 min, 5 min, 30 min, 2 hours, 24 hours). After the retry sequence exhausts, the event is marked as "failed" and visible in the webhook delivery log. Idempotency: each webhook event delivery includes a unique event ID, enabling customer systems to detect and safely discard duplicate deliveries (ensuring at-least-once delivery — events are sent at least once — doesn't produce duplicate data processing). Payload versioning: webhook payload structure must be versioned explicitly so breaking changes to the payload format don't silently break customer integrations. A webhook versioning strategy allows customers to receive the old format for a deprecation window while migrating to the new format. Customer delivery logs: provide a dashboard view of each webhook endpoint's delivery history — timestamp, HTTP response code, delivery latency, and retry count. Customers debugging integration issues need this visibility without requiring support ticket contact. Delivery health alerting: proactively notify customers when their webhook endpoint has sustained failures (>10 consecutive delivery failures) via email, enabling them to fix their endpoint before they miss critical events.

A webhook event catalog is the comprehensive list of events the product can emit, each with its semantic meaning, triggering conditions, and payload structure documentation. Event naming conventions: an event naming scheme should be consistent, readable, and self-descriptive — the resource:action pattern is the most common and cleanest. Examples: ticket.created, ticket.status_changed, subscription.renewed, user.role_updated, account.churned. Avoid ambiguous event names (ticket.updated — what changed?); prefer specific events (ticket.priority_changed, ticket.assignee_changed). Granularity design: err toward more granular events rather than fewer. Customers building integrations can choose which events to subscribe to — they will ignore events that don't apply to their use case, but cannot build a reliable integration if their exact triggering condition is bundled with irrelevant events in a generic "ticket.updated" event. Payload design: every event payload should include: the event type (string), the event ID (unique UUID), the timestamp (ISO 8601 UTC), the resource ID, the current state of the resource (the full resource object after the triggering change), and — for change events — the previous state of the changed attribute. Customer-requested events: maintain a backlog of webhook event requests from customers and integration partners. High-request events with multiple requesting parties are prioritized in the API roadmap.