Docs

Create a notification setting

Creates a new notification setting (notification destination).

POST /notification-settings

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.

Requires notification_setting.write permission.

Request body

descriptionstringrequired
Short description for this notification destination. Shown in the Paddle Dashboard.
Length: 1–500
typestringrequired
Where notifications should be sent for this destination.
Values
  • email
    Deliver to an email address.
  • url
    Deliver to a webhook endpoint.
destinationstringrequired
Webhook endpoint URL or email address.
Length: 1–2048
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.
Min: 1
include_sensitive_fieldsboolean
Default: false
Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to false.
subscribed_eventsarrayrequired
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.
Values
+ Show all values
traffic_sourcestring
Default: platform
Whether Paddle should deliver real platform events, simulation events or both to this notification destination. If omitted, defaults to platform.
Values
  • 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.

Response (201)

dataobjectrequired
Represents a notification destination.
idstringrequired
Example: ntfset_01gt21c5pdx9q1e4mh1xrsjjn6
Unique Paddle ID for this notification setting, prefixed with ntfset_.
Pattern: ^ntfset_[a-z\d]{26}$
descriptionstringrequired
Short description for this notification destination. Shown in the Paddle dashboard.
Length: 1–500
typestringrequired
Where notifications should be sent for this destination.
Values
  • email
    Deliver to an email address.
  • url
    Deliver to a webhook endpoint.
destinationstringrequired
Webhook endpoint URL or email address.
Length: 1–2048
activebooleanrequired
Default: true
Whether Paddle should try to deliver events to this notification destination.
api_versionintegerrequired
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_fieldsbooleanrequired
Default: false
Whether potentially sensitive fields should be sent to this notification destination.
subscribed_eventsarrayrequired
Subscribed events for this notification destination.
namestringrequired
Type of event sent by Paddle, in the format entity.event_type.
Values
+ Show all values
descriptionstringrequired
Example: The subscription.created alert is fired when a new subscription is created.
Short description of this event type.
groupstringrequired
Example: Subscriptions
Group for this event type. Typically the entity that this event relates to.
available_versionsarrayrequired
List of API versions that this event type supports.
endpoint_secret_keystringrequired
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_sourcestringrequired
Whether Paddle should deliver real platform events, simulation events or both to this notification destination.
Values
  • 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.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Request
{
  "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
{
  "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"
  }
}

Was this page helpful?