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

Create an event destination v2

Core Resources
Event Destinations
Create an event destination

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.

    • amazon_eventbridge.aws_account_idstringRequired

      The AWS account ID.

    • amazon_eventbridge.aws_regionstringRequired

      The region of the AWS event source.

  • 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.

    • webhook_endpoint.urlstringRequired

      The URL of the webhook endpoint.

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.

    • amazon_eventbridge.aws_account_idstring

      The AWS account ID.

    • amazon_eventbridge.aws_event_source_arnstring

      The ARN of the AWS event source.

    • amazon_eventbridge.aws_event_source_statusenum

      The state of the AWS event source.

      Possible enum values
      active

      The event source is in active state.

      deleted

      The event source is in deleted state.

      pending

      The event source is in pending state.

      unknown

      The event source state cannot be retrieved.

  • 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.

    • status_details.disablednullable object

      Details about why the event destination has been disabled.

      • status_details.disabled.reasonenum

        Reason event destination has been disabled.

        Possible enum values
        no_aws_event_source_exists

        Event destination has been disabled because the underlying AWS event source does not exist.

        user

        Event destination has been disabled by user.

  • 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.

    • webhook_endpoint.signing_secretnullable string

      The signing secret of the webhook endpoint, only includable on creation.

    • webhook_endpoint.urlnullable string

      The URL of the webhook endpoint, includable.

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