Account2

Addresses4

Adjustments3

API root1

Businesses4

Checkout domains4

Client tokens4

Countries1

Currencies1

Customer portals1

Customers6

Discount groups4

Discounts4

Event types1

Events1

IP addresses1

Metrics9

Notification logs1

Notification settings5

Notifications3

Payment methods3

Prices4

Pricing preview1

Products4

Reports4

Settings18

Simulation run events3

Simulation runs3

Simulation types1

Simulations4

Subscription history1

Subscriptions11

Transactions7

Verifications2

Webhooks

Addresses3

Adjustments2

API keys6

Businesses3

Client tokens3

Customers3

Discount groups2

Discounts3

Payment methods2

Payouts2

Prices3

Products3

Reports2

Subscriptions9

Transactions10

Notification settings

Create a notification setting

Changed on Oct 26, 2026

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.

post/notification-settings

Request

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

Request body

idstring

Unique Paddle ID for this notification setting, prefixed with ntfset_.

descriptionstring required

Short description for this notification destination. Shown in the Paddle Dashboard.

type'email' | 'url' required

Where notifications should be sent for this destination.

destinationstring required

Webhook endpoint URL or email address.

activeboolean

Whether Paddle should try to deliver events to this notification destination.

api_versioninteger

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_fieldsboolean

Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to false.

subscribed_eventsEventTypeName[] 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_keystring

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.

Example request

{
  "id": "ntfset_01gt21c5pdx9q1e4mh1xrsjjn6"
}

Response

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

Example response

{
  "data": {
    "id": "ntfset_01gt21c5pdx9q1e4mh1xrsjjn6",
    "subscribed_events": [
      {
        "description": "The subscription.created alert is fired when a new subscription is created.",
        "group": "Subscriptions"
      }
    ]
  },
  "meta": {
    "request_id": "b15ec92e-8688-40d4-a04d-f44cbec93355"
  }
}

Changes

Oct 26, 2026v1bbc0c72039c8 Revision changes
- breaking
  the request property's maxLength was decreased to 256
Feb 2, 2026v19ba8be0f2006 Revision changes
- breaking
  request body became required
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  removed the enum value all of the request property
- breaking
  removed the enum value email of the request property
- breaking
  removed the enum value platform of the request property
- breaking
  removed the enum value simulation of the request property
- breaking
  removed the enum value url of the request property
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to no type
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the /// response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  added the new api_key_exposure.created enum value to the request property /
- info
  added the new client_token.created enum value to the request property /
- info
  added the new client_token.revoked enum value to the request property /
- info
  added the new client_token.updated enum value to the request property /
- info
  added the new discount_group.created enum value to the request property /
- info
  added the new discount_group.updated enum value to the request property /
- info
  removed the pattern ^ntfset_[a-z\d]{26}$ from the request property
- info
  added to the response property allOf list for the response status
- info
  added to the /// response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  removed the address.created enum value from the /// response property for the response status
- info
  removed the address.imported enum value from the /// response property for the response status
- info
  removed the address.updated enum value from the /// response property for the response status
- info
  removed the adjustment.created enum value from the /// response property for the response status
- info
  removed the adjustment.updated enum value from the /// response property for the response status
- info
  removed the all enum value from the / response property for the response status
- info
  removed the api_key.created enum value from the /// response property for the response status
- info
  removed the api_key.expired enum value from the /// response property for the response status
- info
  removed the api_key.expiring enum value from the /// response property for the response status
- info
  removed the api_key.revoked enum value from the /// response property for the response status
- info
  removed the api_key.updated enum value from the /// response property for the response status
- info
  removed the business.created enum value from the /// response property for the response status
- info
  removed the business.imported enum value from the /// response property for the response status
- info
  removed the business.updated enum value from the /// response property for the response status
- info
  removed the customer.created enum value from the /// response property for the response status
- info
  removed the customer.imported enum value from the /// response property for the response status
- info
  removed the customer.updated enum value from the /// response property for the response status
- info
  removed the discount.created enum value from the /// response property for the response status
- info
  removed the discount.imported enum value from the /// response property for the response status
- info
  removed the discount.updated enum value from the /// response property for the response status
- info
  removed the email enum value from the / response property for the response status
- info
  removed the payment_method.deleted enum value from the /// response property for the response status
- info
  removed the payment_method.saved enum value from the /// response property for the response status
- info
  removed the payout.created enum value from the /// response property for the response status
- info
  removed the payout.paid enum value from the /// response property for the response status
- info
  removed the platform enum value from the / response property for the response status
- info
  removed the price.created enum value from the /// response property for the response status
- info
  removed the price.imported enum value from the /// response property for the response status
- info
  removed the price.updated enum value from the /// response property for the response status
- info
  removed the product.created enum value from the /// response property for the response status
- info
  removed the product.imported enum value from the /// response property for the response status
- info
  removed the product.updated enum value from the /// response property for the response status
- info
  removed the report.created enum value from the /// response property for the response status
- info
  removed the report.updated enum value from the /// response property for the response status
- info
  removed the simulation enum value from the / response property for the response status
- info
  removed the subscription.activated enum value from the /// response property for the response status
- info
  removed the subscription.canceled enum value from the /// response property for the response status
- info
  removed the subscription.created enum value from the /// response property for the response status
- info
  removed the subscription.imported enum value from the /// response property for the response status
- info
  removed the subscription.past_due enum value from the /// response property for the response status
- info
  removed the subscription.paused enum value from the /// response property for the response status
- info
  removed the subscription.resumed enum value from the /// response property for the response status
- info
  removed the subscription.trialing enum value from the /// response property for the response status
- info
  removed the subscription.updated enum value from the /// response property for the response status
- info
  removed the transaction.billed enum value from the /// response property for the response status
- info
  removed the transaction.canceled enum value from the /// response property for the response status
- info
  removed the transaction.completed enum value from the /// response property for the response status
- info
  removed the transaction.created enum value from the /// response property for the response status
- info
  removed the transaction.paid enum value from the /// response property for the response status
- info
  removed the transaction.past_due enum value from the /// response property for the response status
- info
  removed the transaction.payment_failed enum value from the /// response property for the response status
- info
  removed the transaction.ready enum value from the /// response property for the response status
- info
  removed the transaction.revised enum value from the /// response property for the response status
- info
  removed the transaction.updated enum value from the /// response property for the response status
- info
  removed the url enum value from the / response property for the response status
- info
  the / response's property pattern ^ntfset_[a-z\d]{26}$ was removed for the status

Operation history (8 revisions)