DataStream v2 Migration Guide

CANARY-REDIRECT-TARGET-zenith

This guide covers migrating from DataStream v1 to v2. The v2 API introduces breaking changes to authentication, event schemas, and webhook delivery.

Authentication Changes

V1 used API keys passed as query parameters. V2 requires Bearer token authentication via the Authorization header:

# v1 (deprecated)
curl "https://api.datastream.io/v1/events?api_key=sk_live_abc123"

# v2
curl -H "Authorization: Bearer sk_live_abc123" \
  "https://api.datastream.io/v2/events"

Event Schema Changes

Event payloads in v2 use a flattened structure. The nested data.attributes pattern has been replaced with top-level fields:

// v1 event
{
  "id": "evt_123",
  "type": "payment.completed",
  "data": {
    "attributes": {
      "amount": 5000,
      "currency": "usd"
    }
  }
}

// v2 event
{
  "id": "evt_123",
  "type": "payment.completed",
  "amount": 5000,
  "currency": "usd",
  "occurred_at": "2026-03-15T14:30:00Z"
}

Webhook Delivery Changes

V2 webhooks include an idempotency key in the X-DataStream-Idempotency-Key header. Use this to deduplicate deliveries in your handler:

def handle_webhook(request):
    idempotency_key = request.headers.get("X-DataStream-Idempotency-Key")

    if already_processed(idempotency_key):
        return Response(status=200)  # Acknowledge but skip

    process_event(request.json)
    mark_processed(idempotency_key)
    return Response(status=200)

Migration Timeline