Stripe Events API
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.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Events API
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.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/events:
get:
description: >-
<p>List events, going back up to 30 days. Each event data is rendered
according to Stripe API version at its creation time, specified in <a
href="/docs/api/events/object">event object</a> <code>api_version</code>
attribute (not according to your current Stripe API version or
<code>Stripe-Version</code> header).</p>
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.
summary: Stripe Get Events
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Events
- Get
/v1/events/{id}:
get:
description: >-
<p>Retrieves the details of an event. Supply the unique identifier of
the event, which you might have received in a webhook.</p>
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.
summary: Stripe Get Events Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Events
- Get
- Identifiers
components:
schemas:
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
nullable: true
type: string
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.
nullable: true
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
GetEventsRequest:
type: object
properties: {}
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
GetEventsIdRequest:
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
tags:
- name: Events
- name: Get
- name: Identifiers