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
The X-HookStack-Version header allows you to validate the payload version before processing the data, enabling version-specific handling if needed.See Verification docs for more information on how to verify webhook requests from HookStack.

​
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
}
HookStack provides TypeScript definitions for all supported versions to help you implement type-safe webhook handlers.

​
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
Always test your webhook handlers with our testing tools before deploying to production.