# Create an Event Destination

Create a new event destination.

## Request

```curl
curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-09-30.endive" \
  --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

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

## Parameters

- `enabled_events` (array of strings, required)
  The list of event types enabled for delivery to this destination.

- `event_payload` (enum, required)
  Whether to deliver as snapshot or thin events.
Possible enum values:
  - `snapshot`
    Events that contain full resource objects in the delivered payload, rendered using a specified API version.

  - `thin`
    A lightweight event notification with an unversioned payload. It identifies the related Stripe resource so you can retrieve the complete event or the resource’s current state. This reduces coupling to API-versioned object snapshots and makes event handlers easier to maintain.

- `name` (string, required)
  A user-defined label for identifying the destination.

- `type` (enum, required)
  The delivery transport. Chosen when the destination is created and cannot be changed by update.
Possible enum values:
  - `amazon_eventbridge`
    Deliver matching events through a Stripe partner event source in Amazon EventBridge.

  - `azure_event_grid`
    Deliver matching events through a Stripe partner topic in Azure Event Grid.

  - `webhook_endpoint`
    Deliver matching events to a webhook endpoint. Live mode requires HTTPS; sandbox mode also supports HTTP.

- [`amazon_eventbridge`](https://docs.stripe.com/api/v2/core/event-destinations/create.md?query=amazon_eventbridge) (object, optional)
  AWS account and region where Stripe creates the EventBridge partner event source.

- [`azure_event_grid`](https://docs.stripe.com/api/v2/core/event-destinations/create.md?query=azure_event_grid) (object, optional)
  Azure subscription, resource group, and region where Stripe creates the partner topic.

- `description` (string, optional)
  An optional user-defined description of the destination’s purpose.

- `events_from` (array of strings, optional)
  The account or organization scopes that can supply events. Use this with `enabled_events` to define the subscription. `@self`: Receive events from the account that owns the event destination. `@accounts`: Receive events emitted from other accounts you manage, including 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.

- `include` (array of enums, optional)
  Include normally redacted webhook fields in the create response. Public API clients must include `webhook_endpoint.signing_secret` to receive the signing secret.
Possible enum values:
  - `webhook_endpoint.signing_secret`
    Include `webhook_endpoint.signing_secret` in the create response. Public API clients cannot retrieve it later.

  - `webhook_endpoint.url`
    Include the normally redacted `webhook_endpoint.url` in the create response.

- `metadata` (map, optional)
  User-defined key/value data for the destination.

- `snapshot_api_version` (string, optional)
  For snapshot events only, the Stripe API version used to render event objects; do not provide this for thin events.

- [`webhook_endpoint`](https://docs.stripe.com/api/v2/core/event-destinations/create.md?query=webhook_endpoint) (object, optional)
  Delivery target for the webhook endpoint. Live mode requires HTTPS; sandbox mode also supports HTTP.

## Returns

Returns an [Event Destination object](https://docs.stripe.com/api/v2/core/event-destinations/object.md).

## Error Codes

| HTTP status code | Code | Description |
| --- | --- | --- |
| 400 | expired_azure_partner_authorization | Error returned when a user tries to create an event destination with an expired Azure partner authorization. |
| 400 | invalid_azure_partner_authorization | Error returned when a user tries to create an event destination without an Azure partner authorization. |
| 400 | invalid_azure_partner_configuration | Error returned when no valid partner configuration is found using the user provided Azure subscription ID and Azure resource group name. |
| 409 | idempotency_error | An idempotent retry occurred with different request parameters. |