Handling Thin Events with the Hookdeck Event Gateway

View as Markdown

The thin events pattern, where webhooks contain only minimal information and your system fetches complete data from the provider's API, ensures data consistency and simplifies handling of out-of-order events. However, implementing this pattern at scale introduces operational challenges, particularly around overwhelming provider APIs with resource retrieval requests.

Hookdeck's Event Gateway solves these challenges by acting as an intelligent intermediary that decouples event ingestion from processing, supports queuing and throttling, and enables you to implement thin events reliably without hitting API rate limits or processing unnecessary noise.

Core Problem: Avoiding API Rate Limits

The primary operational challenge with thin events is that every webhook triggers an API call to fetch the resource. When you receive hundreds or thousands of webhooks in a short period, your downstream service can easily overwhelm the provider's API with fetch requests, resulting in rate limit errors and failed processing.

Hookdeck's solution: The Event Gateway acts as a durable queue that decouples webhook ingestion from processing. By setting a Max Delivery Rate on your Destination , you control how quickly events are delivered to your application, which directly controls how quickly your handlers fetch data from the provider's API.

Configuring Max Delivery Rate

The key insight is that by throttling event delivery, you can safely process events synchronously in your handler (receive event → fetch resource → process) without risking rate limit errors.

For example, if your provider allows 100 API requests per second and you need to fetch one resource per event, set your max delivery rate to 90 events per second to leave headroom for other API operations.

  1. Open the Connections page
  2. Click the HTTP Destination you want to update
  3. Toggle the Max delivery rate switch
  4. Input a delivery rate value of 90, and choose per second as the unit
  5. Click Save

Use the Update Destination endpoint to set the max delivery rate:

PUT /destinations/:id
{
  "rate_limit": 90,
  "rate_limit_period": "second"
}

Alternative rate configurations:

  • Per minute: { "rate_limit": 5000, "rate_limit_period": "minute" }
  • Per hour: { "rate_limit": 100000, "rate_limit_period": "hour" }
  • Concurrent limit: { "rate_limit": 10, "rate_limit_period": "concurrent" } - processes up to 10 events simultaneously

Implementation Pattern

With rate limiting in place, your webhook handler can use a straightforward synchronous pattern:

async function handleWebhook(request) {
  const { resource_id, event_type } = request.body;
  
  // Safe to fetch synchronously - Event Gateway controls delivery rate
  const resource = await providerAPI.get(`/resources/${resource_id}`);
  
  // Process the latest state
  await processResource(resource);
  
  return { status: 200 };
}

Because the Event Gateway acts as the queue and controls the delivery rate, you don't need to build queueing or batching logic in your application. It handles backpressure for you - events that arrive faster than your configured rate are automatically queued and delivered at a steady pace.

Reducing Noise with Deduplication

Another challenge with thin events at scale is noise: providers often send webhooks for insignificant or rapid changes that don't require fetching data or processing. Each unnecessary webhook still triggers an API fetch in the thin events pattern, wasting API quota and processing resources.

Hookdeck's solution: Use Deduplication rules to filter out redundant or noisy events before they're delivered to your application, reducing the number of API fetches your system performs.

Deduplication Use Case: Rapid Updates

Consider a scenario where a provider sends multiple resource.updated webhooks within seconds for the same resource due to several field changes in quick succession. With thin events, you only care about the final state - you don't need to fetch the resource for each intermediate update.

Configuration:

{
  "type": "deduplicate",
  "window": 300000,
  "include_fields": [
    "body.resource_id",
    "body.event_type"
  ]
}

This configuration suppresses duplicate events for the same resource within a 5-minute window. If you receive 10 resource.updated events for resource_123 within that window, only the first one is delivered, saving 9 unnecessary API fetches.

Deduplication Use Case: Filtering Irrelevant Changes

Some providers send webhooks for every field change, but your application might only care about specific attributes. For example, you might only need to sync when a product's title or price changes, not when inventory quantities fluctuate.

Configuration using field-based deduplication:

{
  "type": "deduplicate",
  "window": 300000,
  "include_fields": [
    "body.resource_id",
    "body.title",
    "body.price",
    "body.status"
  ]
}

By including only the fields you care about in the deduplication key, Hookdeck ignores changes to other fields. An inventory quantity change won't trigger delivery since inventory_quantity isn't in the include_fields list, preventing an unnecessary API fetch.

Alternative approach using exclusions:

{
  "type": "deduplicate",
  "window": 300000,
  "exclude_fields": [
    "body.updated_at",
    "body.inventory_quantity",
    "body.view_count"
  ]
}

This approach is useful when you care about most fields but want to ignore a few volatile ones.

Monitoring Deduplication Impact

Track the effectiveness of your deduplication rules in the Hookdeck dashboard:

  • Events metrics on your Connection page show the total events created vs. events that progressed through to delivery
  • Delivery Rate charts show the reduction in events sent to your destination
  • API Fetch Reduction can be calculated by comparing events received vs. events delivered

Optional Pattern: Transforming Fat Events to Thin Events

While the primary use cases above focus on handling thin events, the Event Gateway can also standardize webhook formats by transforming fat events into thin ones. This is particularly useful when:

  • You want a consistent thin-event handling pattern across multiple providers
  • Some providers send fat events but you prefer to always fetch current state
  • You need to reduce payload sizes for storage or compliance reasons

Transformation Example

Use a Transformation to convert a fat event payload into a thin notification:

addHandler("transform", (request, context) => {
  // Extract only the essential identifiers
  const thinEvent = {
    event_type: request.body.event_type,
    resource_id: request.body.resource.id,
    resource_type: request.body.resource.type,
    occurred_at: request.body.created
  };
  
  // Replace the body with thin event
  request.body = thinEvent;
  
  return request;
});

Before transformation (fat event):

{
  "event_type": "resource.updated",
  "created": "2025-12-01T10:00:00Z",
  "resource": {
    "id": "res_123",
    "type": "product",
    "title": "Premium Widget",
    "price": 99.99,
    "inventory": 150,
    "metadata": { ... }
  }
}

After transformation (thin event):

{
  "event_type": "resource.updated",
  "resource_id": "res_123",
  "resource_type": "product",
  "occurred_at": "2025-12-01T10:00:00Z"
}

Your handler then treats all events uniformly, always fetching current state from the API regardless of the original webhook format.

Observability and Recovery

When implementing thin events, debugging becomes more complex because failures can occur in two places: webhook delivery failures and API fetch failures within your handler. The Event Gateway provides observability for both scenarios.

Request Timeline

Every event processed through Hookdeck is logged with complete details:

  • Delivery Attempts: See all attempts to deliver the event to your destination
  • Response Status: View your handler's HTTP responses and any errors
  • Timing Information: Track latency for delivery and your handler's processing time
  • Payload Inspection: Examine the exact payload delivered at each attempt

Access the Request timeline in the Requests section of the Hookdeck dashboard.

Replay for Recovery

If your downstream service experiences API fetch failures (e.g., temporary provider API outage), you can replay events after the issue is resolved using manual retries.

For a single event:

  1. Locate the event in the dashboard
  2. Click the event to open the details panel
  3. Click Retry to redeliver it to your destination

For multiple events (bulk retry):

  1. Filter events by time range or status (e.g., events that returned 500 errors)
  2. Click Bulk Retry to select all matching events
  3. Click Retry All to redeliver them to your destination

The retry feature is particularly valuable for thin events because it allows you to retry the entire fetch-and-process flow without manual intervention.

Issues and Alerts

Configure Issues to automatically track and alert on delivery failures:

  • Automatic grouping: Similar failures are grouped together for easier investigation
  • Alerting: Get notified via email, Slack, or PagerDuty when issues occur
  • Bulk retry: Retry all events affected by a specific issue with one click

This is especially important for thin events, where a provider API outage can cause cascading fetch failures across many events.

Summary

Hookdeck's Event Gateway makes the thin events pattern operationally viable at scale by solving three core challenges:

  1. API Rate Limiting: Control event delivery rate to stay safely under provider API limits for resource fetches while keeping your handler logic simple and synchronous
  2. Noise Reduction: Use deduplication to filter out redundant events before they trigger unnecessary API fetches
  3. Format Standardization: Optionally transform fat events to thin ones for a consistent handling pattern

Combined with built-in observability and replay capabilities, Hookdeck enables you to implement thin events with confidence, gaining the reliability benefits of always-current data without the operational burden of managing queues, rate limiting, and API errors in your application code.

<- Previous Define Event Types for Outgoing Webhooks Next -> How to Fan Out Webhooks to Different Services