create_notification_setting
Create notification destinations in Paddle to receive webhook or email alerts for billing events like transactions, subscriptions, and customer updates.
Instructions
This tool will create a new notification setting (notification destination) in Paddle.
Create notification destinations to get notifications, like webhooks, for events that happen in Paddle. Paddle recommends handling the storage and provisioning of access after purchase and subscription using webhooks.
The type describes how and where the event should be sent:
email: Deliver to an email address. Add the email address to the destination parameter.
url: Deliver to a webhook endpoint. Add the full URL including the path to the destination parameter.
The destination URL must be publicly accessible. localhost is not a valid address. For local development, use a tunnelling service like ngrok or Hookdeck to generate a public URL.
Pass an array of event type names to subscribedEvents to say which events should be subscribed to. Paddle responds with the full event type object for each event type.
Provide the trafficSource to define if the notification destination should be sent real events and/or simulated test events:
platform: Deliver real platform events. These are sent when real events which are subscribed to take place.
simulation: Deliver simulated events. These are sent when simulations are run to test single events or scenarios, usually to verify implementations of Paddle.
all: Deliver both platform (real) and simulation (test) events.
Create notification destinations as many as needed, but only 10 can be active as per the active boolean parameter. Prompt users to toggle in the dashboard. Alternatively, use the list_notification_setting tool, verify which should be active, and use the update_notification_setting tool to toggle the boolean accordingly.
If successful, the response includes a copy of the new notification setting entity. The endpointSecretKey is returned for webhook signature verification, but is a secure value and should never be shared, never be made publicly-accessible, and should only be stored securely.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Short description for this notification destination. Shown in the Paddle Dashboard. | |
| type | Yes | Where notifications should be sent for this destination. | |
| destination | Yes | Webhook endpoint URL or email address. | |
| apiVersion | No | Must be `1` as the only current valid Paddle API version. If omitted, defaults to `1`. | |
| includeSensitiveFields | No | Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to `false`. | |
| subscribedEvents | Yes | Subscribed events for this notification destination. When creating or updating a notification destination, pass an array of event type names only. | |
| trafficSource | No | Whether Paddle should deliver real platform events, simulation events or both to this notification destination. If omitted, defaults to `platform`. |
Implementation Reference
- src/functions.ts:450-460 (handler)The core handler function that executes the tool logic by calling the Paddle SDK's notificationSettings.create method with validated input parameters.
export const createNotificationSetting = async ( paddle: Paddle, params: z.infer<typeof Parameters.createNotificationSettingParameters>, ) => { try { const notificationSetting = await paddle.notificationSettings.create(params); return notificationSetting; } catch (error) { return error; } }; - src/tools.ts:698-708 (registration)Registers the MCP tool including method name, human-readable name, description prompt, Zod input schema reference, and required permissions/actions.
method: "create_notification_setting", name: "Create a notification setting", description: prompts.createNotificationSettingPrompt, parameters: params.createNotificationSettingParameters, actions: { notificationSettings: { write: true, create: true, }, }, }, - src/tools.ts:701-701 (schema)References the Zod schema for input validation (createNotificationSettingParameters). The actual schema definition is imported from parameters.js.
parameters: params.createNotificationSettingParameters, - src/api.ts:46-46 (registration)Maps the tool method constant to the exported handler function in the central toolMap used by the PaddleAPI.
[TOOL_METHODS.CREATE_NOTIFICATION_SETTING]: funcs.createNotificationSetting, - src/constants.ts:38-38 (registration)Defines the string constant for the tool's method name used across registrations.
CREATE_NOTIFICATION_SETTING: "create_notification_setting",