Event Destinations v2

Learn more about calling API v2 endpoints.

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.

Endpoints

POST/v2/core/event_destinations

POST/v2/core/event_destinations/:id

GET/v2/core/event_destinations/:id

GET/v2/core/event_destinations

DELETE/v2/core/event_destinations/:id

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

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

POST/v2/core/event_destinations/:id/ping

Create an event destination v2

Learn more about calling API v2 endpoints.

Create a new event destination.

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

Server-side language

curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-12-03.preview-v2" \
  --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

Learn more about calling API v2 endpoints.

Update the details of an event destination.

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

Server-side language

curl -X POST https://api.stripe.com/v2/core/event_destinations/ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6 \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-12-03.preview-v2" \
  --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

Learn more about calling API v2 endpoints.

Retrieves the details of an event destination.

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

Server-side language

curl -G https://api.stripe.com/v2/core/event_destinations/ed_test_61RM8ltWcTW4mbsxf16RJyfa2xSQLHJJh1sxm7H0KVT6 \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-12-03.preview-v2" \
  -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 destination v2

Learn more about calling API v2 endpoints.

Lists all event destinations.

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

Server-side language

curl -G https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-12-03.preview-v2" \
  -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
}

Event Destinations v2

Create an event destination v2

Parameters

enabled_eventsarray of stringsRequired

event_payloadenumRequired

namestringRequired

typeenumRequired

amazon_eventbridgeobject

descriptionstring

events_fromarray of enums

includearray of enums

metadatamap

snapshot_api_versionstring

webhook_endpointobject

Returns

Response attributes

idstring

objectstring, value is "v2.core.event_destination"

amazon_eventbridgenullable object

createdtimestamp

descriptionstring

enabled_eventsarray of strings

event_payloadenum

events_fromnullable array of enums

livemodeboolean

metadatanullable map

namestring

snapshot_api_versionnullable string

statusenum

status_detailsnullable object

typeenum

updatedtimestamp

webhook_endpointnullable object

Update an event destination v2

Parameters

idstringRequired

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

createdtimestamp

descriptionstring

enabled_eventsarray of strings

event_payloadenum

events_fromnullable array of enums

livemodeboolean

metadatanullable map

namestring

snapshot_api_versionnullable string

statusenum

status_detailsnullable object

typeenum

updatedtimestamp

webhook_endpointnullable object

Retrieve an event destination v2

Parameters

idstringRequired

includearray of enums

Returns

Response attributes

idstring

objectstring, value is "v2.core.event_destination"

amazon_eventbridgenullable object

createdtimestamp

descriptionstring

enabled_eventsarray of strings

event_payloadenum

events_fromnullable array of enums

livemodeboolean

metadatanullable map

namestring

snapshot_api_versionnullable string

statusenum