> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flokitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Paddle notifications

> Provision, review, and verify the Paddle webhook used by FloKit.AI.

This guide connects an existing Paddle account to FloKit.AI so payment, transaction, customer, and subscription updates can be received reliably.

<Note>
  FloKit.AI creates and maintains the Paddle notification destination for you. Do not create a second destination with the same webhook URL, because Paddle would send duplicate notifications.
</Note>

## Before you start

Make sure that:

* Your Paddle account is already connected in FloKit.AI.
* You can access **Developer tools** in the correct Paddle environment: **Sandbox** or **Live**.
* The Paddle API key stored in FloKit.AI includes **Notification settings: Write** (`notification_setting.write`).

## Connect the webhook

<Steps>
  <Step title="Open Paddle Connectivity in FloKit.AI">
    1. Log in to the [FloKit.AI dashboard](https://dashboard.flokitai.com).
    2. Select the correct App.
    3. Go to **Governance → Payments → Paddle Connectivity**.
  </Step>

  <Step title="Provision the webhook">
    Select **Provision webhook**.

    FloKit.AI creates or updates the Paddle notification destination and then displays its webhook URL.

    Continue when the **Webhook URL** field appears and FloKit.AI confirms **Webhook provisioned with all 16 required events**.
  </Step>

  <Step title="Copy the webhook URL">
    In the **Webhook URL** field, select **Copy URL**.

    Use the URL exactly as shown. Do not edit it, construct it manually, or reuse a URL from another App or Paddle environment.
  </Step>

  <Step title="Open Paddle Notifications">
    1. Open the correct **Sandbox** or **Live** Paddle dashboard.
    2. In the left navigation, select **Developer tools**.
    3. Select **Notifications**.
  </Step>

  <Step title="Open the FloKit.AI destination">
    Find the destination whose URL exactly matches the webhook URL copied from FloKit.AI. Its description starts with `FloKit`.

    Open the action menu next to the destination, then select **Edit destination**.

    <Warning>
      Do not select **New destination** when a destination with the same webhook URL already exists.
    </Warning>
  </Step>

  <Step title="Verify the destination settings">
    Confirm every field below before saving.

    | Paddle field                 | Required value                              |
    | ---------------------------- | ------------------------------------------- |
    | **Description**              | Starts with `FloKit`                        |
    | **Notification type**        | **URL**                                     |
    | **URL or email**             | The exact webhook URL copied from FloKit.AI |
    | **API version**              | **1**                                       |
    | **Usage type — Sandbox**     | **Platform and simulation**                 |
    | **Usage type — Live**        | **Platform**                                |
    | **Include sensitive fields** | **Off**                                     |
    | **Active**                   | **On**                                      |

    Check the URL character by character. It must match the value displayed in FloKit.AI.
  </Step>

  <Step title="Verify the required events">
    In **Subscribed events**, enable all 16 events below. Do not replace this list with **Select all events**.

    **Transactions**

    * `transaction.completed`
    * `transaction.paid`
    * `transaction.payment_failed`
    * `transaction.past_due`

    **Subscriptions**

    * `subscription.created`
    * `subscription.trialing`
    * `subscription.activated`
    * `subscription.updated`
    * `subscription.past_due`
    * `subscription.canceled`
    * `subscription.paused`
    * `subscription.resumed`

    **Adjustments**

    * `adjustment.created`
    * `adjustment.updated`

    **Customers**

    * `customer.created`
    * `customer.updated`
  </Step>

  <Step title="Save the Paddle destination">
    Select **Update destination**.

    If Paddle shows no changes to save, close the destination and continue. FloKit.AI has already configured it correctly.
  </Step>

  <Step title="Test the connection in FloKit.AI">
    1. Return to **Governance → Payments → Paddle Connectivity**.
    2. Select **Test webhook connection**.
    3. Wait for the test to finish.
  </Step>

  <Step title="Confirm the result">
    FloKit.AI reports one of these results:

    * **Webhook connection verified** — the configuration is valid and FloKit.AI has already received a Paddle event. The connection is fully verified.
    * **Webhook configuration verified · Delivery test pending** — the credentials, destination, URL, and 16 required events are valid, but FloKit.AI has not received an event yet.
    * An error message — follow the displayed correction, then run **Test webhook connection** again.

    For complete end-to-end verification, **Last event received** must show a timestamp. In Sandbox, follow [Test delivery in Paddle Sandbox](#test-delivery-in-paddle-sandbox), then run **Test webhook connection** again.
  </Step>
</Steps>

## Test delivery in Paddle Sandbox

Use this only when connecting a Paddle Sandbox account.

1. In Paddle, go to **Developer tools → Simulations**.
2. Select **New simulation**.
3. In **Destination**, select the FloKit.AI notification destination.
4. Enter a clear simulation name, such as `FloKit webhook test`.
5. Select **Single event**.
6. Choose `customer.created`.
7. Select **Create**.
8. Open the simulation and select **Run simulation**.
9. Return to FloKit.AI.
10. Select **Test webhook connection** again.
11. Confirm that FloKit.AI shows **Webhook connection verified** and that **Last event received** has updated.

<Warning>
  Paddle simulations only work when the Sandbox destination's **Usage type** is **Platform and simulation** or **Simulation**.
</Warning>

## Troubleshooting

### FloKit.AI cannot provision the webhook

Confirm that the Paddle API key stored in FloKit.AI includes **Notification settings: Write** (`notification_setting.write`), then select **Provision webhook** again.

### The Paddle destination is missing

Return to FloKit.AI and select **Provision webhook**. Do not create a replacement destination manually.

### The webhook URL does not match

Copy the URL again from FloKit.AI, open **Developer tools → Notifications → Edit destination** in Paddle, replace the URL, and select **Update destination**.

### The connection test fails

Confirm that the destination is active, uses API version **1**, has the correct usage type, and includes all 16 required events. Then run **Test webhook connection** again.

### The configuration is verified, but delivery is pending

Run a Paddle Sandbox simulation or complete a test transaction that generates one of the required events. Then return to FloKit.AI and select **Test webhook connection** again.

### A Sandbox simulation cannot use the destination

Open the destination in Paddle and change **Usage type** to **Platform and simulation**, then select **Update destination**.

### Paddle reports too many active destinations

Paddle allows a maximum of 10 active notification destinations. Deactivate an unused destination, then provision the FloKit.AI webhook again.