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

# Create or update notification destinations

Create webhook destinations to tell Paddle which events you want to receive and where to deliver them to. Once added, you can update, deactivate, and delete destinations.

---

A notification destination is a webhook endpoint or email address that Paddle sends notifications about events to. It's called a notification setting in the API.

## Use an AI agent

## Create a notification destination

Create a notification destination to start receiving notifications for events. You can choose the kind of events that you want to receive notifications for.

{% callout type="info" %}
You can create as many notification destinations as you want, but only 10 can be active at once.
{% /callout %}

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Developer tools > Notifications**.
2. Click {% mock-button icon="carbon:add" %}New destination
3. Enter the details for your new notification destination.
4. Choose the events that you want to receive notifications for.
5. Click Save destination when you're done.

{% /instruction-steps %}

{% /dashboard-instructions %}

{% collapsible title="Field descriptions" %}

{% definition-list %}
{% definition term="Description" %}
Short description for this notification destination.
{% /definition %}
{% definition term="Notification type" %}
Whether you want to send events to a webhook endpoint or an email address.
{% /definition %}
{% definition term="URL or email" %}
Webhook endpoint URL or email address to send events to.
{% /definition %}
{% definition term="API version" %}
API version that entities for events should conform to.
{% /definition %}
{% definition term="Usage type" %}
Whether this destination receives real platform events, simulation events, or both.
{% /definition %}
{% /definition-list %}

{% /collapsible %}

{% /tab-item %}

{% tab-item title="API" %}

Create a notification destination using the API in two steps:

1. **List event types and extract names**  
   Query the API to learn about the events that you can subscribe to, then extract names.
2. **Create your destination**  
   Build a request that includes details of your destination and an array of strings for the events you want to receive, then send your request.

### List event types and extract names {% step=true badge="Optional" %}

Event types are actions that Paddle creates events for. To create a notification destination, you'll need to tell Paddle which event types you want to get notifications for.

Send a `GET` request to the `/event-types` endpoint to get a list of all event types. Review the response, then extract `data[].name` for the events that you want to subscribe to and save these for later — we'll use this in the next step.

{% api-example method="GET" path="/event-types" href="/api-reference/products/create-product" %}

```json
{
  "data": [
    {
      "name": "transaction.billed",
      "description": "Occurs when a transaction is billed. Its status field changes to billed and billed_at is populated.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.canceled",
      "description": "Occurs when a transaction is canceled. Its status field changes to canceled.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.completed",
      "description": "Occurs when a transaction is completed. Its status field changes to completed.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.created",
      "description": "Occurs when a transaction is created.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.paid",
      "description": "Occurs when a transaction is paid. Its status field changes to paid.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.past_due",
      "description": "Occurs when a transaction becomes past due. Its status field changes to past_due.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.payment_failed",
      "description": "Occurs when a payment fails for a transaction. The payments array is updated with details of the payment attempt.",
      "group": "Transaction",
      "available_versions": [1]
    },
    {
      "name": "transaction.ready",
      "description": "Occurs when a transaction is ready to be billed. Its status field changes to 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 becomes active. Its status field changes to active. This means any trial period has elapsed and Paddle has successfully billed the customer.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.canceled",
      "description": "Occurs when a subscription is canceled. Its status field changes to canceled.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.created",
      "description": "Occurs when a subscription is created. subscription.trialing or subscription.activated typically follow.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.imported",
      "description": "Occurs when a subscription is imported.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.past_due",
      "description": "Occurs when a subscription has an unpaid transaction. Its status changes to past_due.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.paused",
      "description": "Occurs when a subscription is paused. Its status field changes to paused.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.resumed",
      "description": "Occurs when a subscription is resumed after being paused. Its status field changes to active.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.trialing",
      "description": "Occurs when a subscription enters trial period.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "subscription.updated",
      "description": "Occurs when a subscription is updated.",
      "group": "Subscription",
      "available_versions": [1]
    },
    {
      "name": "product.created",
      "description": "Occurs when a product is created.",
      "group": "Product",
      "available_versions": [1]
    },
    {
      "name": "product.imported",
      "description": "Occurs when a product is imported.",
      "group": "Product",
      "available_versions": [1]
    },
    {
      "name": "product.updated",
      "description": "Occurs when a product is updated.",
      "group": "Product",
      "available_versions": [1]
    },
    {
      "name": "price.created",
      "description": "Occurs when a price is created.",
      "group": "Price",
      "available_versions": [1]
    },
    {
      "name": "price.imported",
      "description": "Occurs when a price is imported.",
      "group": "Price",
      "available_versions": [1]
    },
    {
      "name": "price.updated",
      "description": "Occurs when a price is updated.",
      "group": "Price",
      "available_versions": [1]
    },
    {
      "name": "customer.created",
      "description": "Occurs when a customer is created.",
      "group": "Customer",
      "available_versions": [1]
    },
    {
      "name": "customer.imported",
      "description": "Occurs when a customer is imported.",
      "group": "Customer",
      "available_versions": [1]
    },
    {
      "name": "customer.updated",
      "description": "Occurs when a customer is updated.",
      "group": "Customer",
      "available_versions": [1]
    },
    {
      "name": "address.created",
      "description": "Occurs when an address is created.",
      "group": "Address",
      "available_versions": [1]
    },
    {
      "name": "address.imported",
      "description": "Occurs when a address is imported.",
      "group": "Address",
      "available_versions": [1]
    },
    {
      "name": "address.updated",
      "description": "Occurs when an address is updated.",
      "group": "Address",
      "available_versions": [1]
    },
    {
      "name": "business.created",
      "description": "Occurs when a business is created.",
      "group": "Business",
      "available_versions": [1]
    },
    {
      "name": "business.imported",
      "description": "Occurs when a business is imported.",
      "group": "Business",
      "available_versions": [1]
    },
    {
      "name": "business.updated",
      "description": "Occurs when a business is updated.",
      "group": "Business",
      "available_versions": [1]
    },
    {
      "name": "adjustment.created",
      "description": "Occurs when an adjustment is created.",
      "group": "Adjustment",
      "available_versions": [1]
    },
    {
      "name": "adjustment.updated",
      "description": "Occurs when an adjustment is updated, the only time an adjustment will be updated is when the status changes from pending to approved or from pending to rejected.",
      "group": "Adjustment",
      "available_versions": [1]
    },
    {
      "name": "payout.created",
      "description": "Occurs when a payout is created.",
      "group": "Payout",
      "available_versions": [1]
    },
    {
      "name": "payout.paid",
      "description": "Occurs when a payout is paid.",
      "group": "Payout",
      "available_versions": [1]
    },
    {
      "name": "discount.created",
      "description": "Occurs when a discount is created.",
      "group": "Discount",
      "available_versions": [1]
    },
    {
      "name": "discount.imported",
      "description": "Occurs when a discount is imported.",
      "group": "Discount",
      "available_versions": [1]
    },
    {
      "name": "discount.updated",
      "description": "Occurs when a discount is updated.",
      "group": "Discount",
      "available_versions": [1]
    },
    {
      "name": "report.created",
      "description": "Occurs when a report is created.",
      "group": "Report",
      "available_versions": [1]
    },
    {
      "name": "report.updated",
      "description": "Occurs when a report is updated.",
      "group": "Report",
      "available_versions": [1]
    }
  ],
  "meta": {
    "request_id": "364194bd-2f30-4cfb-8190-ce5a774efa0a"
  }
}
```

{% /api-example %}

### Create your destination {% step=true %}

Build a request that includes information about your destination.

- The value for `destination` changes depending on the `type`. For `email`, pass a valid email address. For `url`, pass a valid URL.
- Pass an array of strings as `events` for the events you want to receive notifications for.
- Pass `traffic_source` to determine whether this destination receives real platform events, simulation events, or both.

Send a `POST` request to the `/notification-settings` endpoint with the request you built.
If successful, Paddle responds with a copy of the new notification destination.

The response includes an object for each subscribed event with details about that event, and an `endpoint_secret_key` that you can use to [verify events come from Paddle](https://developer.paddle.com/webhooks/signature-verification.md).

{% callout type="warning" %}
Treat your endpoint secret key like a password. Keep it safe and never share it with apps or people you don't trust.
{% /callout %}

{% api-example method="POST" path="/notification-settings" href="/api-reference/products/create-product" %}

```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"
  ]
}
```

```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"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Update a notification destination

Once you've created a notification destination, you can change its description, destination URL or email, what kind of traffic it receives, and the events it's subscribed to.

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Developer tools > Notifications**.
2. Click the  button next to a notification destination in the list, then choose {% mock-button icon="carbon:edit" %}Edit destination from the menu.
3. Edit notification destination details and subscribed events.
4. Click Update destination when you're done.

{% /instruction-steps %}

{% /dashboard-instructions %}

{% /tab-item %}
{% tab-item title="API" %}

Send a `PATCH` request to the `/notification-settings/{notification_setting_id}` endpoint, passing the ID of the notification destination as a path parameter. Include only the fields you want to update. Omitted fields remain unchanged.

If successful, Paddle responds with a copy of the updated notification destination.

{% api-example method="PATCH" path="/notification-settings/{notification_setting_id}" href="/api-reference/notification-settings/update-notification-setting" %}

```json
{
  "description": "Slack notifications (old)",
  "active": false
}
```

```json
{
  "data": {
    "id": "ntfset_01gkpjp8bkm3tm53kdgkx6sms7",
    "description": "Slack notifications (old)",
    "type": "url",
    "destination": "https://hooks.slack.com/example",
    "active": false,
    "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": "be464f91-8050-49df-a351-994b25da3714"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Deactivate a notification destination

Deactivate a notification destination to stop Paddle from sending notifications for events to it. Deactivation is useful if you need to make changes to a webhook endpoint server or integration. You can reactivate later, if needed.

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Developer tools > Notifications**.
2. Click the  button next to a notification destination in the list, then choose {% mock-button icon="carbon:trash-can" %}Deactivate from the menu.
3. Click Deactivate destination on the confirmation dialog.

You can reactivate later by choosing Activate from the menu.
{% /instruction-steps %}

{% /dashboard-instructions %}

{% /tab-item %}
{% tab-item title="API" %}

Send a `PATCH` request to the `/notification-settings/{notification_setting_id}` endpoint, setting `active` to `false`.

If successful, Paddle responds with a copy of the updated notification destination. Paddle no longer tries to deliver notifications for subscribed events.

{% api-example method="PATCH" path="/notification-settings/{notification_setting_id}" href="/api-reference/notification-settings/update-notification-setting" %}

```json
{
  "description": "Slack notifications (old)",
  "active": false
}
```

```json
{
  "data": {
    "id": "ntfset_01gkpjp8bkm3tm53kdgkx6sms7",
    "description": "Slack notifications (old)",
    "type": "url",
    "destination": "https://hooks.slack.com/example",
    "active": false,
    "api_version": 1,
    "include_sensitive_fields": false,
    "traffic_source": "platform",
    "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": "df1f7d45-5d2b-4fcd-9a7d-2122145547b4"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Delete a notification destination

{% callout type="danger" %}
There's no way to recover a deleted notification destination. [Deactivate a notification destination](#deactivate-a-notification-destination) if you'll need access to the logs or want to reactivate later.
{% /callout %}

Delete a notification destination to permanently remove it from your Paddle account. Paddle stops sending notifications for events to your destination and you lose access to all delivery logs for it.

You can only delete notification destinations using the API.

Send a `DELETE` request to the `/notification-settings/{notification_setting_id}` endpoint, passing the ID of the notification destination as a path parameter. If successful, Paddle returns `204 No Content` with no response body.

{% api-endpoint method="DELETE" path="/notification-settings/{notification_setting_id}" %}

{% /api-endpoint %}

## Troubleshooting

{% accordion %}

{% accordion-item title="Why can't I save a notification destination?" %}

If you're having trouble creating, updating, or activating a notification destination, check that:

- The webhook endpoint URL or email address you're using is correctly formatted.
- You've not exceeded the limit for active notifications. You can have up to 10 active notification destinations. [Deactivate a notification destination](#deactivate-destination) before creating a new one.
- You set the correct notification type. Simulated events can only be delivered to webhook destinations and can't be delivered to email destinations. Change the **Notification type** to **URL** or the **Usage type** to **Platform only** in the dashboard, or change `type` to `url` or `traffic_source` to `platform` in the API request.

{% /accordion-item %}

{% accordion-item title="Why aren't notifications being delivered to a notification destination?" %}

If you're not receiving **either type** of notification:

- Check that you subscribed to the events you're expecting to receive. You'll only receive notifications for events that you checked when configuring the notification destination. This includes [simulated events](https://developer.paddle.com/webhooks/test-webhooks.md), too. Simulated events can't be sent to email destinations.
- Check that you entered the correct email address or webhook endpoint URL.

If you're not receiving **webhook** notifications:

- Review your webhook logs to see if there are any delivery errors or timeout issues. Go to **Paddle > Developer tools > Notifications**, click the  button next to a destination in the list, then choose View logs to review.
- Make sure the endpoint is accessible and responding with `2xx` status codes.

{% /accordion-item %}

{% /accordion %}