Event Destinations v2

Set up an event destination to receive events from Stripe across multiple destination types, including webhook endpoints and Amazon EventBridge. Event destinations support receiving thin events and snapshot events.

Learn more about calling API v2 endpoints.

Was this section helpful?Yes No

Create an Event Destination

POST/v2/core/event_destinations

Update an Event Destination

POST/v2/core/event_destinations/:id

Retrieve an Event Destination

GET/v2/core/event_destinations/:id

List Event Destinations

GET/v2/core/event_destinations

Delete an Event Destination

DELETE/v2/core/event_destinations/:id

Disable an Event Destination

POST/v2/core/event_destinations/:id/disable

Enable an Event Destination

POST/v2/core/event_destinations/:id/enable

The Event Destination object v2

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.

azure_event_gridnullable object
Azure Event Grid 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 strings
Specifies which accounts’ events route to this destination. @self: Receive events from the account that owns the event destination. @accounts: Receive events emitted from other accounts you manage which includes your v1 and v2 accounts. @organization_members: Receive events from accounts directly linked to the organization. @organization_members/@accounts: Receive events from all accounts connected to any platform accounts in the organization.

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.
azure_event_grid
Azure Event Grid.
webhook_endpoint
Webhook endpoint.

updatedtimestamp
Time at which the object was last updated.

webhook_endpointnullable object
Webhook endpoint configuration.

The Event Destination object

{
  "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"
  }
}

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.
azure_event_grid
Azure Event Grid.
webhook_endpoint
Webhook endpoint.

amazon_eventbridgeobject
Amazon EventBridge configuration.

azure_event_gridobject
Azure Event Grid configuration.

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

events_fromarray of strings
Specifies which accounts’ events route to this destination. @self: Receive events from the account that owns the event destination. @accounts: Receive events emitted from other accounts you manage which includes your v1 and v2 accounts. @organization_members: Receive events from accounts directly linked to the organization. @organization_members/@accounts: Receive events from all accounts connected to any platform accounts in the organization.

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.

azure_event_gridnullable object
Azure Event Grid 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 strings
Specifies which accounts’ events route to this destination. @self: Receive events from the account that owns the event destination. @accounts: Receive events emitted from other accounts you manage which includes your v1 and v2 accounts. @organization_members: Receive events from accounts directly linked to the organization. @organization_members/@accounts: Receive events from all accounts connected to any platform accounts in the organization.

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.
azure_event_grid
Azure Event Grid.
webhook_endpoint
Webhook endpoint.

updatedtimestamp
Time at which the object was last updated.

webhook_endpointnullable object
Webhook endpoint configuration.

Error Codes

400expired_azure_partner_authorization

Error returned when a user tries to create an event destination with an expired Azure partner authorization.

400invalid_azure_partner_authorization

Error returned when a user tries to create an event destination without an Azure partner authorization.

400invalid_azure_partner_configuration

Error returned when no valid partner configuration is found using the user provided Azure subscription ID and Azure resource group name.

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: 2026-05-27.dahlia" \
  --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

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.

azure_event_gridnullable object
Azure Event Grid 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 strings
Specifies which accounts’ events route to this destination. @self: Receive events from the account that owns the event destination. @accounts: Receive events emitted from other accounts you manage which includes your v1 and v2 accounts. @organization_members: Receive events from accounts directly linked to the organization. @organization_members/@accounts: Receive events from all accounts connected to any platform accounts in the organization.

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.
azure_event_grid
Azure Event Grid.
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: 2026-05-27.dahlia" \
  --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

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.

azure_event_gridnullable object
Azure Event Grid 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 strings
Specifies which accounts’ events route to this destination. @self: Receive events from the account that owns the event destination. @accounts: Receive events emitted from other accounts you manage which includes your v1 and v2 accounts. @organization_members: Receive events from accounts directly linked to the organization. @organization_members/@accounts: Receive events from all accounts connected to any platform accounts in the organization.

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.
azure_event_grid
Azure Event Grid.
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: 2026-05-27.dahlia" \
  -d "include[0]=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
  }
}

Event Destinations v2

The Event Destination object v2

Attributes

idstring

objectstring, value is "v2.core.event_destination"

amazon_eventbridgenullable object

azure_event_gridnullable object

createdtimestamp

descriptionstring

enabled_eventsarray of strings

event_payloadenum

events_fromnullable array of strings

livemodeboolean

metadatanullable map

namestring

snapshot_api_versionnullable string

statusenum

status_detailsnullable object

typeenum

updatedtimestamp

webhook_endpointnullable object

Create an Event Destination v2

Parameters

enabled_eventsarray of stringsRequired

event_payloadenumRequired

namestringRequired

typeenumRequired

amazon_eventbridgeobject

azure_event_gridobject

descriptionstring

events_fromarray of strings

includearray of enums

metadatamap

snapshot_api_versionstring

webhook_endpointobject

Returns

Response attributes

idstring

objectstring, value is "v2.core.event_destination"

amazon_eventbridgenullable object

azure_event_gridnullable object

createdtimestamp

descriptionstring

enabled_eventsarray of strings

event_payloadenum

events_fromnullable array of strings

livemodeboolean

metadatanullable map

namestring

snapshot_api_versionnullable string

statusenum

status_detailsnullable object

typeenum

updatedtimestamp

webhook_endpointnullable object

Update an Event Destination v2

Parameters

descriptionstring

enabled_eventsarray of strings

includearray of enums

metadatamap

namestring

webhook_endpointobject

Returns

Response attributes

idstring

objectstring, value is "v2.core.event_destination"

amazon_eventbridgenullable object

azure_event_gridnullable object

createdtimestamp

descriptionstring

enabled_eventsarray of strings

event_payloadenum

events_fromnullable array of strings

livemodeboolean

metadatanullable map

namestring

snapshot_api_versionnullable string

statusenum

status_detailsnullable object