Data Versioning

HookStack implements a robust versioning system for webhook payloads to ensure compatibility and reliability across different API versions. This guide explains how payload versioning works and how to handle different versions in your implementations.

​

Overview

When HookStack sends webhooks to your endpoints, each payload includes version information in both the headers and the payload structure. This allows your systems to handle different versions of the webhook data format appropriately.

​

Webhook Payload Structure

Every webhook payload follows this standardized structure:

type WebhookPayload = {
  data: object,             // The actual payload data
  event: {
    source: string          // The source of the event (e.g., 'stripe', 'front')
  },
  metadata: {
    attempt: number         // Number of delivery attempts
    requestId: string       // Unique request identifier
    timestamp: number       // Timestamp of the webhook attempt
    webhookEventId: string  // Unique event identifier
    webhookId: string       // ID of the webhook configuration
  },
  version: string           // Current payload version (e.g., "v1.0")
}

​

Version Headers

HookStack includes version information in the HTTP headers of each webhook request:

X-HookStack-Version: v1.0

​

Version Compatibility

HookStack maintains backward compatibility for all supported versions. When we introduce breaking changes, we:

1. Release a new version number
2. Maintain support for older versions for a deprecation period
3. Notify users through our changelog and email notifications

​

Best Practices

1. Always check the version header before processing webhooks
2. Implement version-specific handlers if you need to support multiple versions
3. Subscribe to our changelog to stay informed about version updates
4. Use type definitions for better payload handling:

   interface WebhookPayloadV1 {
     data: Record<string, unknown>
     event: {
       source: string
     }
     metadata: {
       attempt: number
       requestId: string
       timestamp: number
       webhookEventId: string
       webhookId: string
     }
     version: string
   }
   

​

Migration Guide

When upgrading to a new version:

1. Add support for the new version while maintaining old version handlers
2. Test your implementation with our webhook testing tools
3. Monitor webhook delivery success rates during the transition
4. Remove old version handlers only after the deprecation period