Stripe Events API

openapi: 3.2.0
info:
  title: Stripe Events API
  description: Needs description.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Events
paths:
  /v1/events:
    get:
      description: List events, going back up to 30 days. Each event data is rendered according to Stripe API version at its creation time, specified in event object api_version attribute (not according to your current Stripe API version or Stripe-Version header).
      operationId: GetEvents
      parameters:
      - explode: true
        in: query
        name: created
        required: false
        schema:
          anyOf:
          - properties:
              gt:
                type: integer
              gte:
                type: integer
              lt:
                type: integer
              lte:
                type: integer
            title: range_query_specs
            type: object
          - type: integer
        style: deepObject
      - description: Filter events by whether all webhooks were successfully delivered. If false, events which are still pending or have failed all delivery attempts to a webhook endpoint will be returned.
        in: query
        name: delivery_success
        required: false
        schema:
          type: boolean
        style: form
      - description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        in: query
        name: ending_before
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      - description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
        in: query
        name: starting_after
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: A string containing a specific event name, or group of events using * as a wildcard. The list will be filtered to include only events with a matching event property.
        in: query
        name: type
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: An array of up to 20 strings containing specific event names. The list will be filtered to include only events with a matching event property. You may pass either `type` or `types`, but not both.
        explode: true
        in: query
        name: types
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetEventsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/NotificationEventList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Events
      summary: Get events
      x-summary-source: derived
  /v1/events/{id}:
    get:
      description: Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.
      operationId: GetEventsId
      parameters:
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      - in: path
        name: id
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetEventsIdRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Events
      summary: Get events id
      x-summary-source: derived
components:
  schemas:
    GetEventsIdRequest:
      type: object
      properties: {}
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    event:
      description: 'Events are our way of letting you know when something interesting happens in

        your account. When an interesting event occurs, we create a new `Event`

        object. For example, when a charge succeeds, we create a `charge.succeeded`

        event, and when an invoice payment attempt fails, we create an

        `invoice.payment_failed` event. Certain API requests might create multiple

        events. For example, if you create a new subscription for a

        customer, you receive both a `customer.subscription.created` event and a

        `charge.succeeded` event.


        Events occur when the state of another API resource changes. The event''s data

        field embeds the resource''s state at the time of the change. For

        example, a `charge.succeeded` event contains a charge, and an

        `invoice.payment_failed` event contains an invoice.


        As with other API resources, you can use endpoints to retrieve an

        [individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)

        from the API. We also have a separate

        [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the

        `Event` objects directly to an endpoint on your server. You can manage

        webhooks in your

        [account settings](https://dashboard.stripe.com/account/webhooks). Learn how

        to [listen for events](https://stripe.com/docs/webhooks)

        so that your integration can automatically trigger reactions.


        When using [Connect](https://stripe.com/docs/connect), you can also receive event notifications

        that occur in connected accounts. For these events, there''s an

        additional `account` attribute in the received `Event` object.


        We only guarantee access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event)

        for 30 days.'
      properties:
        account:
          description: The connected account that originates the event.
          maxLength: 5000
          type: string
        api_version:
          description: The Stripe API version used to render `data`. This property is populated only for events on or after October 31, 2014.
          maxLength: 5000
          type:
          - string
          - 'null'
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        data:
          $ref: '#/components/schemas/notification_event_data'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        livemode:
          description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
          type: boolean
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - event
          type: string
        pending_webhooks:
          description: Number of webhooks that haven't been successfully delivered (for example, to return a 20x response) to the URLs you specify.
          type: integer
        request:
          anyOf:
          - $ref: '#/components/schemas/notification_event_request'
          description: Information on the API request that triggers the event.
        type:
          description: Description of the event (for example, `invoice.created` or `charge.refunded`).
          maxLength: 5000
          type: string
      required:
      - created
      - data
      - id
      - livemode
      - object
      - pending_webhooks
      - type
      title: NotificationEvent
      type: object
      x-expandableFields:
      - data
      - request
      x-resourceId: event
    NotificationEventList:
      type: object
      required:
      - data
      - has_more
      - object
      - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/event'
          type: array
        has_more:
          description: True if this list has another page of items after this one that can be fetched.
          type: boolean
        object:
          description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
          enum:
          - list
          type: string
        url:
          description: The URL where this list can be accessed.
          maxLength: 5000
          pattern: ^/v1/events
          type: string
    GetEventsRequest:
      type: object
      properties: {}
  securitySchemes:
    basicAuth:
      description: 'Basic HTTP authentication. Allowed headers-- Authorization: Basic <api_key> | Authorization: Basic <base64 hash of `api_key:`>'
      scheme: basic
      type: http
    bearerAuth:
      bearerFormat: auth-scheme
      description: 'Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>'
      scheme: bearer
      type: http