> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# POST /notification-settings

**Create a notification setting**

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.

**Required permissions:** `notification_setting.write`

## Request body

- `description`: string (required) — Short description for this notification destination. Shown in the Paddle Dashboard. (Length: 1–500)
- `type`: string (required) — Where notifications should be sent for this destination.
  - `email` — Deliver to an email address.
  - `url` — Deliver to a webhook endpoint.
- `destination`: string (required) — Webhook endpoint URL or email address. (Length: 1–2048)
- `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. (Min: 1)
- `include_sensitive_fields`: boolean — Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to `false`. (default: `false`)
- `subscribed_events`: array (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.
  - `address.created` — An [`address.created`](https://developer.paddle.com/webhooks/addresses/address-created) event.
  - `address.imported` — An [`address.imported`](https://developer.paddle.com/webhooks/addresses/address-imported) event.
  - `address.updated` — An [`address.updated`](https://developer.paddle.com/webhooks/addresses/address-updated) event.
  - `adjustment.created` — An [`adjustment.created`](https://developer.paddle.com/webhooks/adjustments/adjustment-created) event.
  - `adjustment.updated` — An [`adjustment.updated`](https://developer.paddle.com/webhooks/adjustments/adjustment-updated) event.
  - `api_key.created` — An [`api_key.created`](https://developer.paddle.com/webhooks/api-keys/api-key-created) event.
  - `api_key.expired` — An [`api_key.expired`](https://developer.paddle.com/webhooks/api-keys/api-key-expired) event.
  - `api_key.expiring` — An [`api_key.expiring`](https://developer.paddle.com/webhooks/api-keys/api-key-expiring) event.
  - `api_key.revoked` — An [`api_key.revoked`](https://developer.paddle.com/webhooks/api-keys/api-key-revoked) event.
  - `api_key.updated` — An [`api_key.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-updated) event.
  - `api_key_exposure.created` — An [`api_key_exposure.created`](https://developer.paddle.com/webhooks/api-key-exposures/api-key-exposure-created) event.
  - `business.created` — A [`business.created`](https://developer.paddle.com/webhooks/businesses/business-created) event.
  - `business.imported` — A [`business.imported`](https://developer.paddle.com/webhooks/businesses/business-imported) event.
  - `business.updated` — A [`business.updated`](https://developer.paddle.com/webhooks/businesses/business-updated) event.
  - `client_token.created` — A [`client_token.created`](https://developer.paddle.com/webhooks/client-tokens/client-token-created) event.
  - `client_token.revoked` — A [`client_token.revoked`](https://developer.paddle.com/webhooks/client-tokens/client-token-revoked) event.
  - `client_token.updated` — A [`client_token.updated`](https://developer.paddle.com/webhooks/client-tokens/client-token-updated) event.
  - `customer.created` — A [`customer.created`](https://developer.paddle.com/webhooks/customers/customer-created) event.
  - `customer.imported` — A [`customer.imported`](https://developer.paddle.com/webhooks/customers/customer-imported) event.
  - `customer.updated` — A [`customer.updated`](https://developer.paddle.com/webhooks/customers/customer-updated) event.
  - `discount.created` — A [`discount.created`](https://developer.paddle.com/webhooks/discounts/discount-created) event.
  - `discount.imported` — A [`discount.imported`](https://developer.paddle.com/webhooks/discounts/discount-imported) event.
  - `discount.updated` — A [`discount.updated`](https://developer.paddle.com/webhooks/discounts/discount-updated) event.
  - `discount_group.created` — A [`discount_group.created`](https://developer.paddle.com/webhooks/discount-groups/discount-group-created) event.
  - `discount_group.updated` — A [`discount_group.updated`](https://developer.paddle.com/webhooks/discount-groups/discount-group-updated) event.
  - `payment_method.saved` — A [`payment_method.saved`](https://developer.paddle.com/webhooks/payment-methods/payment-method-saved) event.
  - `payment_method.deleted` — A [`payment_method.deleted`](https://developer.paddle.com/webhooks/payment-methods/payment-method-deleted) event.
  - `payout.created` — A [`payout.created`](https://developer.paddle.com/webhooks/payouts/payout-created) event.
  - `payout.paid` — A [`payout.paid`](https://developer.paddle.com/webhooks/payouts/payout-paid) event.
  - `price.created` — A [`price.created`](https://developer.paddle.com/webhooks/prices/price-created) event.
  - `price.imported` — A [`price.imported`](https://developer.paddle.com/webhooks/prices/price-imported) event.
  - `price.updated` — A [`price.updated`](https://developer.paddle.com/webhooks/prices/price-updated) event.
  - `product.created` — A [`product.created`](https://developer.paddle.com/webhooks/products/product-created) event.
  - `product.imported` — A [`product.imported`](https://developer.paddle.com/webhooks/products/product-imported) event.
  - `product.updated` — A [`product.updated`](https://developer.paddle.com/webhooks/products/product-updated) event.
  - `report.created` — A [`report.created`](https://developer.paddle.com/webhooks/reports/report-created) event.
  - `report.updated` — A [`report.updated`](https://developer.paddle.com/webhooks/reports/report-updated) event.
  - `subscription.activated` — A [`subscription.activated`](https://developer.paddle.com/webhooks/subscriptions/subscription-activated) event.
  - `subscription.canceled` — A [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled) event.
  - `subscription.created` — A [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created) event.
  - `subscription.imported` — A [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported) event.
  - `subscription.past_due` — A [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due) event.
  - `subscription.paused` — A [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused) event.
  - `subscription.resumed` — A [`subscription.resumed`](https://developer.paddle.com/webhooks/subscriptions/subscription-resumed) event.
  - `subscription.trialing` — A [`subscription.trialing`](https://developer.paddle.com/webhooks/subscriptions/subscription-trialing) event.
  - `subscription.updated` — A [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated) event.
  - `transaction.billed` — A [`transaction.billed`](https://developer.paddle.com/webhooks/transactions/transaction-billed) event.
  - `transaction.canceled` — A [`transaction.canceled`](https://developer.paddle.com/webhooks/transactions/transaction-canceled) event.
  - `transaction.completed` — A [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed) event.
  - `transaction.created` — A [`transaction.created`](https://developer.paddle.com/webhooks/transactions/transaction-created) event.
  - `transaction.paid` — A [`transaction.paid`](https://developer.paddle.com/webhooks/transactions/transaction-paid) event.
  - `transaction.past_due` — A [`transaction.past_due`](https://developer.paddle.com/webhooks/transactions/transaction-past-due) event.
  - `transaction.payment_failed` — A [`transaction.payment_failed`](https://developer.paddle.com/webhooks/transactions/transaction-payment-failed) event.
  - `transaction.ready` — A [`transaction.ready`](https://developer.paddle.com/webhooks/transactions/transaction-ready) event.
  - `transaction.revised` — A [`transaction.revised`](https://developer.paddle.com/webhooks/transactions/transaction-revised) event.
  - `transaction.updated` — A [`transaction.updated`](https://developer.paddle.com/webhooks/transactions/transaction-updated) event.
- `traffic_source`: string — Whether Paddle should deliver real platform events, simulation events or both to this notification destination. If omitted, defaults to `platform`. (default: `"platform"`)
  - `platform` — Deliver real platform events to this notification destination.
  - `simulation` — Deliver simulation events to this notification destination.
  - `all` — Deliver platform and simulation events to this notification destination.

### Request example

```json
{
  "description": "Slack notifications",
  "type": "url",
  "destination": "https://hooks.slack.com/example",
  "api_version": 1,
  "traffic_source": "all",
  "subscribed_events": [
    "transaction.billed",
    "transaction.canceled",
    "transaction.completed",
    "transaction.created",
    "transaction.payment_failed",
    "transaction.ready",
    "transaction.updated",
    "subscription.activated",
    "subscription.created",
    "subscription.past_due",
    "subscription.paused",
    "subscription.resumed",
    "subscription.trialing",
    "subscription.updated"
  ]
}
```

## Response (201)

- `data`: object (required) — Represents a notification destination.
  - `id`: string (required) — Unique Paddle ID for this notification setting, prefixed with `ntfset_`. (pattern: `^ntfset_[a-z\d]{26}$`)
  - `description`: string (required) — Short description for this notification destination. Shown in the Paddle dashboard. (Length: 1–500)
  - `type`: string (required) — Where notifications should be sent for this destination.
    - `email` — Deliver to an email address.
    - `url` — Deliver to a webhook endpoint.
  - `destination`: string (required) — Webhook endpoint URL or email address. (Length: 1–2048)
  - `active`: boolean (required) — Whether Paddle should try to deliver events to this notification destination. (default: `true`)
  - `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. (Min: 1)
  - `include_sensitive_fields`: boolean (required) — Whether potentially sensitive fields should be sent to this notification destination. (default: `false`)
  - `subscribed_events`: array (required) — Subscribed events for this notification destination.
  - `endpoint_secret_key`: string (required) — Webhook destination secret key, prefixed with `pdl_ntfset_`. Used for signature verification. (pattern: `^pdl_ntfset_[a-zA-Z0-9]{26}_[a-zA-Z0-9]{32}$`)
  - `traffic_source`: string (required) — Whether Paddle should deliver real platform events, simulation events or both to this notification destination.
    - `platform` — Deliver real platform events to this notification destination.
    - `simulation` — Deliver simulation events to this notification destination.
    - `all` — Deliver platform and simulation events to this notification destination.
- `meta`: object (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.

### Response example

```json
{
  "data": {
    "id": "ntfset_01gkpjp8bkm3tm53kdgkx6sms7",
    "description": "Slack notifications",
    "type": "url",
    "destination": "https://hooks.slack.com/example",
    "active": true,
    "api_version": 1,
    "include_sensitive_fields": false,
    "traffic_source": "all",
    "subscribed_events": [
      {
        "name": "transaction.billed",
        "description": "Occurs when a transaction is billed.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "transaction.canceled",
        "description": "Occurs when a transaction is canceled.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "transaction.completed",
        "description": "Occurs when a transaction is completed.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "transaction.created",
        "description": "Occurs when a transaction is created.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "transaction.payment_failed",
        "description": "Occurs when a payment fails for a transaction.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "transaction.ready",
        "description": "Occurs when a transaction is ready.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "transaction.updated",
        "description": "Occurs when a transaction is updated.",
        "group": "Transaction",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.activated",
        "description": "Occurs when a subscription is activated.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.canceled",
        "description": "Occurs when a subscription is canceled.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.created",
        "description": "Occurs when a subscription is created.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.past_due",
        "description": "Occurs when a subscription is past due.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.paused",
        "description": "Occurs when a subscription is paused.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.resumed",
        "description": "Occurs when a subscription is resumed.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.trialing",
        "description": "Occurs when a subscription is trialing.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      },
      {
        "name": "subscription.updated",
        "description": "Occurs when a subscription is updated.",
        "group": "Subscription",
        "available_versions": [
          1
        ]
      }
    ],
    "endpoint_secret_key": "pdl_ntfset_01gkpjp8bkm3tm53kdgkx6sms7_6h3qd3uFSi9YCD3OLYAShQI90XTI5vEI"
  },
  "meta": {
    "request_id": "fd55d51a-6242-4645-8572-af2a8b6f41b6"
  }
}
```