Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Events

Snapshot events allow you to track and react to activity in your Stripe integration. When the state of another API resource changes, Stripe creates an Event object that contains all the relevant information associated with that action, including the affected API resource. For example, a successful payment triggers a charge.succeeded event, which contains the Charge in the event’s data property. Some actions trigger multiple events. For example, if you create a new subscription for a customer, it triggers both a customer.subscription.created event and a charge.succeeded event.

Configure an event destination in your account to listen for events that represent actions your integration needs to respond to. Additionally, you can retrieve an individual event or a list of events from the API.

Connect platforms can also receive event notifications that occur in their connected accounts. These events include an account attribute that identifies the relevant connected account.

You can access events through the Retrieve Event API for 30 days.

Was this section helpful?YesNo
Retrieve an event
GET/v1/events/:id
List all events
GET/v1/events

The Event object

Attributes

  • idstring

    Unique identifier for the object.

  • api_versionnullable string

    The Stripe API version used to render data when the event was created. The contents of data never change, so this value remains static regardless of the API version currently in use. This property is populated only for events created on or after October 31, 2014.

  • dataobject

    Object containing data associated with the event.

  • requestnullable object

    Information on the API request that triggers the event.

  • typestring

    Description of the event (for example, invoice.created or charge.refunded).

More attributes

  • objectstring

  • accountnullable stringConnect only

  • contextnullable string

  • createdtimestamp

  • livemodeboolean

  • pending_webhooksinteger

The Event object
{
  "id": "",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,
  "data": {
    "object": {
      "id": "",
      "object": "setup_intent",
      "application": null,
      "automatic_payment_methods": null,
      "cancellation_reason": null,
      "client_secret": "seti_1NG8Du2eZvKYlo2C9XMqbR0x_secret_O2CdhLwGFh2Aej7bCY7qp8jlIuyR8DJ",
      "created": 1686089970,
      "customer": null,
      "description": null,
      "flow_directions": null,
      "last_setup_error": null,
      "latest_attempt": null,
      "livemode": false,
      "mandate": null,
      "metadata": {},
      "next_action": null,
      "on_behalf_of": null,
      "payment_method": "",
      "payment_method_options": {
        "acss_debit": {
          "currency": "cad",
          "mandate_options": {
            "interval_description": "First day of every month",
            "payment_schedule": "interval",
            "transaction_type": "personal"
          },
          "verification_method": "automatic"
        }
      },
      "payment_method_types": [
        "acss_debit"
      ],
      "single_use_mandate": null,
      "status": "requires_confirmation",
      "usage": "off_session"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "setup_intent.created"
}

Retrieve an event

Retrieves the details of an event if it was created in the last 30 days. Supply the unique identifier of the event, which you might have received in a webhook.

Parameters

No parameters.

Returns

Returns an event object if a valid identifier was provided. All events share a common structure, detailed to the right. The only property that will differ is the data property.

In each case, the data dictionary will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, a customer.created event will have the same information as retrieving the relevant customer would.

In cases where the attributes of an object have changed, data will also contain a dictionary containing the changes.

curl https://api.stripe.com/v1/events/ \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,
  "data": {
    "object": {
      "id": "",
      "object": "setup_intent",
      "application": null,
      "automatic_payment_methods": null,
      "cancellation_reason": null,
      "client_secret": "seti_1NG8Du2eZvKYlo2C9XMqbR0x_secret_O2CdhLwGFh2Aej7bCY7qp8jlIuyR8DJ",
      "created": 1686089970,
      "customer": null,
      "description": null,
      "flow_directions": null,
      "last_setup_error": null,
      "latest_attempt": null,
      "livemode": false,
      "mandate": null,
      "metadata": {},
      "next_action": null,
      "on_behalf_of": null,
      "payment_method": "",
      "payment_method_options": {
        "acss_debit": {
          "currency": "cad",
          "mandate_options": {
            "interval_description": "First day of every month",
            "payment_schedule": "interval",
            "transaction_type": "personal"
          },
          "verification_method": "automatic"
        }
      },
      "payment_method_types": [
        "acss_debit"
      ],
      "single_use_mandate": null,
      "status": "requires_confirmation",
      "usage": "off_session"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "setup_intent.created"
}