> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstack.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Versioning

> Understanding how HookStack handles webhook payload 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:

```typescript
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:

```plaintext
X-HookStack-Version: v1.0
```

<Note>
  The `X-HookStack-Version` header allows you to validate the payload version before processing the
  data, enabling version-specific handling if needed.

  See [Verification](/essentials/verification) docs for more information on how to verify webhook
  requests from HookStack.
</Note>

## 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:
   ```typescript
   interface WebhookPayloadV1 {
     data: Record<string, unknown>
     event: {
       source: string
     }
     metadata: {
       attempt: number
       requestId: string
       timestamp: number
       webhookEventId: string
       webhookId: string
     }
     version: string
   }
   ```

<Note>
  HookStack provides TypeScript definitions for all supported versions to help you implement type-safe webhook handlers.
</Note>

## 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

<Warning>
  Always test your webhook handlers with our testing tools before deploying to production.
</Warning>