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

Create an event destination v2

Create a new event destination.

Learn more about calling API v2 endpoints.

Parameters

  • enabled_eventsarray of stringsRequired

    The list of events to enable for this endpoint.

  • event_payloadenumRequired

    Payload type of events being subscribed to.

    Possible enum values
    snapshot

    Events from v1 APIs.

    thin

    Events from v2 APIs.

  • namestringRequired

    Event destination name.

  • typeenumRequired

    Event destination type.

    Possible enum values
    amazon_eventbridge

    Amazon EventBridge.

    webhook_endpoint

    Webhook endpoint.

  • amazon_eventbridgeobject

    Amazon EventBridge configuration.

  • descriptionstring

    An optional description of what the event destination is used for.

  • events_fromarray of enums

    Where events should be routed from.

    Possible enum values
    other_accounts

    Receive events from accounts connected to the account that owns the event destination.

    self

    Receive events from the account that owns the event destination.

  • includearray of enums

    Additional fields to include in the response.

    Possible enum values
    webhook_endpoint.signing_secret

    Include parameter to expose webhook_endpoint.signing_secret.

    webhook_endpoint.url

    Include parameter to expose webhook_endpoint.url.

  • metadatamap

    Metadata.

  • snapshot_api_versionstring

    If using the snapshot event payload, the API version events are rendered as.

  • webhook_endpointobject

    Webhook endpoint configuration.

Returns

Response attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "v2.core.event_destination"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • amazon_eventbridgenullable object

    Amazon EventBridge configuration.

  • createdtimestamp

    Time at which the object was created.

  • descriptionstring

    An optional description of what the event destination is used for.

  • enabled_eventsarray of strings

    The list of events to enable for this endpoint.

  • event_payloadenum

    Payload type of events being subscribed to.

    Possible enum values
    snapshot

    Events from v1 APIs.

    thin

    Events from v2 APIs.

  • events_fromnullable array of enums

    Where events should be routed from.

    Possible enum values
    other_accounts

    Receive events from accounts connected to the account that owns the event destination.

    self

    Receive events from the account that owns the event destination.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • metadatanullable map

    Metadata.

  • namestring

    Event destination name.

  • snapshot_api_versionnullable string

    If using the snapshot event payload, the API version events are rendered as.

  • statusenum

    Status. It can be set to either enabled or disabled.

    Possible enum values
    disabled

    Event destination is disabled.

    enabled

    Event destination is enabled.

  • status_detailsnullable object

    Additional information about event destination status.

  • typeenum

    Event destination type.

    Possible enum values
    amazon_eventbridge

    Amazon EventBridge.

    webhook_endpoint

    Webhook endpoint.

  • updatedtimestamp

    Time at which the object was last updated.

  • webhook_endpointnullable object

    Webhook endpoint configuration.

Error Codes
409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/core/event_destinations
curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "name": "My Event Destination",
    "description": "This is my event destination, I like it a lot",
    "enabled_events": [
        "v1.billing.meter.error_report_triggered"
    ],
    "type": "webhook_endpoint",
    "webhook_endpoint": {
        "url": "https://example.com/my/webhook/endpoint"
    },
    "event_payload": "thin",
    "include": [
        "webhook_endpoint.url"
    ]
  }'
Response
{
  "id": "ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6",
  "object": "v2.core.event_destination",
  "created": "2024-10-22T16:20:09.931Z",
  "description": "This is my event destination, I like it a lot",
  "enabled_events": [
    "v1.billing.meter.error_report_triggered"
  ],
  "event_payload": "thin",
  "events_from": [
    "self"
  ],
  "livemode": false,
  "metadata": {},
  "name": "My Event Destination",
  "snapshot_api_version": null,
  "status": "enabled",
  "status_details": null,
  "type": "webhook_endpoint",
  "updated": "2024-10-22T16:20:09.937Z",
  "webhook_endpoint": {
    "signing_secret": null,
    "url": "https://example.com/my/webhook/endpoint"
  }
}

Update an event destination v2

Update the details of an event destination.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    Identifier for the event destination to update.

  • descriptionstring

    An optional description of what the event destination is used for.

  • enabled_eventsarray of strings

    The list of events to enable for this endpoint.

  • includearray of enums

    Additional fields to include in the response. Currently supports webhook_endpoint.url.

    Possible enum values
    webhook_endpoint.url

    Include parameter to expose webhook_endpoint.url.

  • metadatamap

    Metadata.

  • namestring

    Event destination name.

  • webhook_endpointobject

    Webhook endpoint configuration.

Returns

Response attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "v2.core.event_destination"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • amazon_eventbridgenullable object

    Amazon EventBridge configuration.

  • createdtimestamp

    Time at which the object was created.

  • descriptionstring

    An optional description of what the event destination is used for.

  • enabled_eventsarray of strings

    The list of events to enable for this endpoint.

  • event_payloadenum

    Payload type of events being subscribed to.

    Possible enum values
    snapshot

    Events from v1 APIs.

    thin

    Events from v2 APIs.

  • events_fromnullable array of enums

    Where events should be routed from.

    Possible enum values
    other_accounts

    Receive events from accounts connected to the account that owns the event destination.

    self

    Receive events from the account that owns the event destination.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • metadatanullable map

    Metadata.

  • namestring

    Event destination name.

  • snapshot_api_versionnullable string

    If using the snapshot event payload, the API version events are rendered as.

  • statusenum

    Status. It can be set to either enabled or disabled.

    Possible enum values
    disabled

    Event destination is disabled.

    enabled

    Event destination is enabled.

  • status_detailsnullable object

    Additional information about event destination status.

  • typeenum

    Event destination type.

    Possible enum values
    amazon_eventbridge

    Amazon EventBridge.

    webhook_endpoint

    Webhook endpoint.

  • updatedtimestamp

    Time at which the object was last updated.

  • webhook_endpointnullable object

    Webhook endpoint configuration.

Error Codes
404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/core/event_destinations/:id
curl -X POST https://api.stripe.com/v2/core/event_destinations/ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6 \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "description": "A better description",
    "enabled_events": [
        "v1.billing.meter.error_report_triggered",
        "v1.billing.meter.no_meter_found"
    ],
    "include": [
        "webhook_endpoint.url"
    ]
  }'
Response
{
  "id": "ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6",
  "object": "v2.core.event_destination",
  "created": "2024-10-22T16:20:09.931Z",
  "description": "A better description",
  "enabled_events": [
    "v1.billing.meter.error_report_triggered",
    "v1.billing.meter.no_meter_found"
  ],
  "event_payload": "thin",
  "events_from": [
    "self"
  ],
  "livemode": false,
  "metadata": {},
  "name": "My Event Destination",
  "snapshot_api_version": null,
  "status": "disabled",
  "status_details": {
    "disabled": {
      "reason": "user"
    }
  },
  "type": "webhook_endpoint",
  "updated": "2024-10-22T16:25:48.976Z",
  "webhook_endpoint": {
    "signing_secret": null,
    "url": "https://example.com/my/webhook/endpoint"
  }
}

Retrieve an event destination v2

Retrieves the details of an event destination.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    Identifier for the event destination to retrieve.

  • includearray of enums

    Additional fields to include in the response.

    Possible enum values
    webhook_endpoint.url

    Include parameter to expose webhook_endpoint.url.

Returns

Response attributes

  • idstring

    Unique identifier for the object.

  • objectstring, value is "v2.core.event_destination"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • amazon_eventbridgenullable object

    Amazon EventBridge configuration.

  • createdtimestamp

    Time at which the object was created.

  • descriptionstring

    An optional description of what the event destination is used for.

  • enabled_eventsarray of strings

    The list of events to enable for this endpoint.

  • event_payloadenum

    Payload type of events being subscribed to.

    Possible enum values
    snapshot

    Events from v1 APIs.

    thin

    Events from v2 APIs.

  • events_fromnullable array of enums

    Where events should be routed from.

    Possible enum values
    other_accounts

    Receive events from accounts connected to the account that owns the event destination.

    self

    Receive events from the account that owns the event destination.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • metadatanullable map

    Metadata.

  • namestring

    Event destination name.

  • snapshot_api_versionnullable string

    If using the snapshot event payload, the API version events are rendered as.

  • statusenum

    Status. It can be set to either enabled or disabled.

    Possible enum values
    disabled

    Event destination is disabled.

    enabled

    Event destination is enabled.

  • status_detailsnullable object

    Additional information about event destination status.

  • typeenum

    Event destination type.

    Possible enum values
    amazon_eventbridge

    Amazon EventBridge.

    webhook_endpoint

    Webhook endpoint.

  • updatedtimestamp

    Time at which the object was last updated.

  • webhook_endpointnullable object

    Webhook endpoint configuration.

Error Codes
404not_found

The resource wasn’t found.

GET /v2/core/event_destinations/:id
curl -G https://api.stripe.com/v2/core/event_destinations/ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6 \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  -d include="webhook_endpoint.url"
Response
{
  "id": "ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6",
  "object": "v2.core.event_destination",
  "created": "2024-10-22T16:20:09.931Z",
  "description": "This is my event destination, I like it a lot",
  "enabled_events": [
    "v1.billing.meter.error_report_triggered"
  ],
  "event_payload": "thin",
  "events_from": [
    "self"
  ],
  "livemode": false,
  "metadata": {},
  "name": "My Event Destination",
  "snapshot_api_version": null,
  "status": "disabled",
  "status_details": {
    "disabled": {
      "reason": "user"
    }
  },
  "type": "webhook_endpoint",
  "updated": "2024-10-22T16:22:02.524Z",
  "webhook_endpoint": {
    "signing_secret": null,
    "url": null
  }
}

List all event destinations v2

Lists all event destinations.

Learn more about calling API v2 endpoints.

Parameters

  • includearray of enums

    Additional fields to include in the response. Currently supports webhook_endpoint.url.

    Possible enum values
    webhook_endpoint.url

    Include parameter to expose webhook_endpoint.url.

  • limitinteger

    The page size.

  • pagestring

    The requested page.

Returns

Response attributes

  • dataarray of objects

    List of event destinations.

  • next_page_urlnullable string

    The next page url.

  • previous_page_urlnullable string

    The previous page url.

GET /v2/core/event_destinations
curl -G https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  -d include="webhook_endpoint.url"
Response
{
  "data": [
    {
      "id": "ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6",
      "object": "v2.core.event_destination",
      "created": "2024-10-22T16:20:09.931Z",
      "description": "This is my event destination, I like it a lot",
      "enabled_events": [
        "v1.billing.meter.error_report_triggered"
      ],
      "event_payload": "thin",
      "events_from": [
        "self"
      ],
      "livemode": false,
      "metadata": {},
      "name": "My Event Destination",
      "snapshot_api_version": null,
      "status": "disabled",
      "status_details": {
        "disabled": {
          "reason": "user"
        }
      },
      "type": "webhook_endpoint",
      "updated": "2024-10-22T16:22:02.524Z",
      "webhook_endpoint": {
        "signing_secret": null,
        "url": null
      }
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Delete an event destination v2

Delete an event destination.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    Identifier for the event destination to delete.

Returns

Response attributes

  • idstring

    Identifier for the deleted event destination.

Error Codes
404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

DELETE /v2/core/event_destinations/:id
curl -X DELETE https://api.stripe.com/v2/core/event_destinations/ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6 \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview"
Response
{
  "id": "ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6"
}