# Stripe Event

> Stripe webhook event wrapper with versioned data object and request tracking.

- Name: `stripe-event`
- Categories: stripe
- Depends on: `@open-types/stripe-shared`
- Detail page: https://open-types.dev/types/stripe-event

## Install

```bash
# Types only
npx shadcn add @open-types/stripe-event

# Types + Zod v4 validators
npx shadcn add @open-types/stripe-event-zod

# Types + real-world examples
npx shadcn add @open-types/stripe-event-examples
```

## Types

```typescript
import type { StripeMetadata } from "./stripe-shared";

export interface StripeEventData {
  object: Record<string, unknown>;
  previous_attributes?: Record<string, unknown>;
}

export interface StripeEventRequest {
  id: string | null;
  idempotency_key: string | null;
}

export interface StripeEvent {
  id: string;
  object: "event";
  api_version: string | null;
  created: number;
  data: StripeEventData;
  livemode: boolean;
  pending_webhooks: number;
  request: StripeEventRequest | null;
  type: string;
}

export type { StripeMetadata };
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  StripeEvent,
  StripeEventData,
  StripeEventRequest,
} from "../types/stripe-event";

export const stripeEventDataSchema = z.object({
  object: z.record(z.string(), z.unknown()),
  previous_attributes: z.record(z.string(), z.unknown()).optional(),
}) satisfies z.ZodType<StripeEventData>;

export const stripeEventRequestSchema = z.object({
  id: z.string().nullable(),
  idempotency_key: z.string().nullable(),
}) satisfies z.ZodType<StripeEventRequest>;

export const stripeEventSchema = z.object({
  id: z.string(),
  object: z.literal("event"),
  api_version: z.string().nullable(),
  created: z.number(),
  data: stripeEventDataSchema,
  livemode: z.boolean(),
  pending_webhooks: z.number(),
  request: stripeEventRequestSchema.nullable(),
  type: z.string(),
}) satisfies z.ZodType<StripeEvent>;

export type {
  StripeEvent,
  StripeEventData,
  StripeEventRequest,
} from "../types/stripe-event";
```

## Examples

```typescript
// Source: https://docs.stripe.com/api/events/object
// Captured: 2026-05
import type {
  StripeEventData,
  StripeEventRequest,
  StripeEvent,
} from "../types/stripe-event";
import { stripeIds } from "./shared/stripe.examples";

const paymentIntentObject = {
  id: stripeIds.paymentIntent,
  object: "payment_intent",
  amount: 2000,
  currency: "usd",
  metadata: { order_id: "ord_123" },
} as const;

export const stripeEventDataExamples = {
  withPrevious: {
    object: paymentIntentObject,
    previous_attributes: { status: "requires_payment_method" },
  } satisfies StripeEventData,
  withoutPrevious: { object: paymentIntentObject } satisfies StripeEventData,
  emptyPrevious: {
    object: paymentIntentObject,
    previous_attributes: {},
  } satisfies StripeEventData,
} as const;

export const stripeEventRequestExamples = {
  full: {
    id: stripeIds.request,
    idempotency_key: "stripe-demo-key-123",
  } satisfies StripeEventRequest,
  bothNull: { id: null, idempotency_key: null } satisfies StripeEventRequest,
  noIdempotencyKey: { id: stripeIds.request, idempotency_key: null } satisfies StripeEventRequest,
} as const;

const baseEvent = {
  id: stripeIds.event,
  object: "event",
  api_version: "2023-10-16",
  created: 1712948400,
  data: stripeEventDataExamples.withPrevious,
  livemode: false,
  pending_webhooks: 2,
  request: stripeEventRequestExamples.full,
  type: "payment_intent.succeeded",
} as const satisfies StripeEvent;

export const stripeEventExamples = {
  paymentIntentSucceeded: baseEvent,
  paymentIntentFailed: {
    ...baseEvent,
    id: "evt_1Ot8q12eZvKYlo2Cfail0001",
    type: "payment_intent.payment_failed",
    data: {
      object: { ...paymentIntentObject, status: "requires_payment_method" },
      previous_attributes: { status: "processing" },
    },
  } satisfies StripeEvent,
  invoicePaid: {
    ...baseEvent,
    id: "evt_1Ot8q12eZvKYlo2Cinv0002",
    type: "invoice.paid",
    data: {
      object: {
        id: stripeIds.invoice,
        object: "invoice",
        status: "paid",
        amount_paid: 2500,
      },
    },
    request: stripeEventRequestExamples.bothNull,
  } satisfies StripeEvent,
  customerCreated: {
    ...baseEvent,
    id: "evt_1Ot8q12eZvKYlo2Ccus0003",
    type: "customer.created",
    request: null,
    api_version: null,
    livemode: true,
    pending_webhooks: 0,
    data: { object: { id: stripeIds.customer, object: "customer" } },
  } satisfies StripeEvent,
} as const;
```