What Are Thin Events?

Thin events are webhook payloads that contain minimal information—typically just an event type and a resource identifier—rather than the full state of the resource. They serve as notifications that something has changed, signaling to the receiver that they should fetch the latest data from the provider's API.

This notification-only pattern is increasingly recognized as a best practice for building reliable webhook-driven systems, as it ensures you're always working with the most current data rather than a potentially stale snapshot.

Thin Events vs. Fat Events

In event-driven architecture, there are two primary approaches to designing webhook payloads:

Fat Events (Event-Carried State Transfer)

Fat events include the complete state of a resource within the webhook payload itself. When you receive the event, you have all the information you need to process it without making additional API calls.

Advantages:

  • Immediate access to data without extra API calls
  • Reduced API usage and potential cost savings
  • Can process events even if the provider's API is temporarily unavailable

Disadvantages:

  • The data in the payload may be stale or outdated by the time you process it
  • Vulnerable to ordering issues (an older event processed after a newer one can corrupt your state)
  • Larger payload sizes, which can impact network transfer and storage
  • Requires careful handling of duplicate events to maintain data consistency

Thin Events (Notification Pattern)

Thin events contain only the essential information to identify what changed—usually an event type and a resource ID—forcing you to fetch the full, current state from the API.

Advantages:

  • Always work with the most up-to-date data
  • Naturally handles out-of-order events (the latest API fetch returns current state)
  • Simplifies idempotency logic (processing is based on actual state, not event sequence)
  • Smaller payload sizes

Disadvantages:

  • Requires an additional API call for each event
  • Increases API usage, which can hit rate limits at scale
  • Dependent on the provider's API availability

How Thin Events Work

The conceptual flow of the thin event pattern is straightforward:

sequenceDiagram
    participant ProviderAPI as API Provider
    participant YourSystem as Your System

    ProviderAPI->>YourSystem: Thin Event (Notification)<br/>{ id: "res_123", type: "resource.updated" }
    YourSystem->>ProviderAPI: GET /resources/res_123
    ProviderAPI-->>YourSystem: Current Resource State
    YourSystem->>YourSystem: Process Latest Data
  1. Receive Notification: Your system receives a thin event indicating that a resource has changed
  2. Fetch Latest State: Before processing, you make an API call to retrieve the current state of the resource
  3. Process Current Data: You process the resource using the latest data from the API, not the event payload

This pattern ensures that even if events arrive out of order or are duplicated, your system always processes the most current state of the resource.

Industry Adoption

While the thin event pattern has long been considered a best practice in distributed systems design, major providers are now formalizing this approach. Stripe, one of the largest webhook providers, is adopting thin events as part of their API evolution to help developers build more reliable integrations.

However, the pattern itself is universal and can be applied to webhooks from any provider. Even if a provider sends fat events, you can choose to ignore the payload data and fetch the resource from their API instead—effectively treating their events as thin notifications.

Implementation Considerations

While thin events provide significant data consistency benefits, they do introduce challenges at scale, particularly around API rate limiting. When your system receives a high volume of webhooks in a short period, fetching the resource for each event can quickly exceed the provider's API rate limits.

For practical guidance on implementing thin events in production systems, including error handling, retry logic, and operational best practices, see Best Practices for Working With Thin Events.

To implement thin events effectively while avoiding rate limit issues, see our guide on the Webhooks Fetch Before Process Pattern, which covers strategies for decoupling ingestion from processing using queues and throttling.

For broader context on event-driven patterns and design principles, refer to Event-Driven Architecture Fundamentals.

Summary

Thin events represent a notification-only approach to webhooks that prioritizes data consistency over convenience. By treating webhook payloads as signals rather than source of truth, you build systems that are resilient to common event-driven challenges like ordering issues and duplicates. While this pattern requires careful implementation—particularly around API rate management—it provides a strong foundation for reliable, scalable webhook integrations.

What's a Webhook