---
title: "Create a notification setting"
method: POST
path: "/notification-settings"
tags: ["Notification settings"]
---

# Create a notification setting

`POST /notification-settings`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/notification-settings`
- Auth: HTTP bearer

Creates a new notification setting (notification destination).

Pass an array of event type names to `subscribed_events` to say which events you'd like to subscribe to. Paddle responds with the full event type object for each event type.

If successful, your response includes a copy of the new notification setting entity. Use the returned `endpoint_secret_key` for webhook signature verification.

## Request body

- NotificationSettingCreate: Represents a notification destination when creating notification destinations.
  - `id` string: Unique Paddle ID for this notification setting, prefixed with `ntfset_`.
  - `description` string, required: Short description for this notification destination. Shown in the Paddle Dashboard.
  - `type` 'email' | 'url', required: Where notifications should be sent for this destination.
  - `destination` string, required: Webhook endpoint URL or email address.
  - `active` boolean: Whether Paddle should try to deliver events to this notification destination.
  - `api_version` integer: API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Can't be a version older than your account default. If omitted, defaults to your account default version.
  - `include_sensitive_fields` boolean: Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to `false`.
  - `subscribed_events` EventTypeName[], required: Subscribed events for this notification destination. When creating or updating a notification destination, pass an array of event type names only. Paddle returns the complete event type object.
  - `endpoint_secret_key` string: Webhook destination secret key, prefixed with `pdl_ntfset_`. Used for signature verification.
  - `traffic_source` 'platform' | 'simulation' | 'all': Whether Paddle should deliver real platform events, simulation events or both to this notification destination.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- object
  - `data` NotificationSetting, required: Represents a notification destination.
    - `id` string, required: Unique Paddle ID for this notification setting, prefixed with `ntfset_`.
    - `description` string, required: Short description for this notification destination. Shown in the Paddle dashboard.
    - `type` 'email' | 'url', required: Where notifications should be sent for this destination.
    - `destination` string, required: Webhook endpoint URL or email address.
    - `active` boolean, required: Whether Paddle should try to deliver events to this notification destination.
    - `api_version` integer, required: API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Can't be a version older than your account default.
    - `include_sensitive_fields` boolean, required: Whether potentially sensitive fields should be sent to this notification destination.
    - `subscribed_events` EventType[], required: Subscribed events for this notification destination.
      - `name` 'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated', required: Type of event sent by Paddle, in the format `entity.event_type`.
      - `description` string, required: Short description of this event type.
      - `group` string, required: Group for this event type. Typically the entity that this event relates to.
      - `available_versions` integer[], required: List of API versions that this event type supports.
    - `endpoint_secret_key` string, required: Webhook destination secret key, prefixed with `pdl_ntfset_`. Used for signature verification.
    - `traffic_source` 'platform' | 'simulation' | 'all', required: Whether Paddle should deliver real platform events, simulation events or both to this notification destination.
  - `meta` Meta, required: Information about this response.
    - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-10-26** (v1) `bbc0c72039c8`: 1 breaking
  - the `description` request property's maxLength was decreased to `256`
- **2026-02-02** (v1) `9ba8be0f2006`: 20 breaking, 1 warning, 84 info
  - request body became required
  - added `#/components/schemas/NotificationSettingId` to the `id` request property `allOf` list
  - added `#/components/schemas/NotificationSettingTrafficSource` to the `traffic_source` request property `allOf` list
  - added `#/components/schemas/NotificationSettingType` to the `type` request property `allOf` list
  - …101 more
- **2025-05-27** (v1) `e57c515077cc`: 5 warning, 5 info
  - added the new `api_key.created` enum value to the `data/subscribed_events/items/name` response property for the response status `201`
  - added the new `api_key.expired` enum value to the `data/subscribed_events/items/name` response property for the response status `201`
  - added the new `api_key.expiring` enum value to the `data/subscribed_events/items/name` response property for the response status `201`
  - added the new `api_key.revoked` enum value to the `data/subscribed_events/items/name` response property for the response status `201`
  - …6 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/notification-settings/post.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)