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

# Paddle Webhook Setup Guide

> Configure Paddle to deliver events to StackOne.

## Prerequisites

Before continuing, you should have already completed the following for this connector:

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/connect/managing-connectors/overview">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/paddle/guides/connector-profile/api-key" icon="https://stackone-logos.com/api/paddle/filled/svg" horizontal>
        Paddle - API Key
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/embed/account-linking/overview">StackOne Hub</a> or <a href="/embed/account-linking/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/paddle/guides/link-account/api-key" icon="https://stackone-logos.com/api/paddle/filled/svg" horizontal>
        Paddle - API Key
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Subscribe via the StackOne dashboard</h2>

  <p>This connector uses <strong>Programmatic Webhooks</strong>. When you enable webhook events for a connected Paddle account, StackOne automatically registers a notification setting in Paddle via the API.</p>

  <Steps>
    <Step title="Select event subscriptions in the dashboard">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the StackOne dashboard, open the Paddle connector profile and enable the webhook events you want to receive. See the <strong>Available Webhook Events</strong> section below for the full list.</p>
      </div>
    </Step>

    <Step title="Connect the Paddle account">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On account connection (or when event subscriptions change), StackOne registers the webhook in Paddle on your behalf using the connected account's API key. The notification setting is created via `POST /notification-settings`. Each account receives its own dedicated notification setting.</p>
      </div>
    </Step>

    <Step title="Verify delivery">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Trigger a matching change in Paddle (for example, create a test customer or subscription) and confirm the event reaches your downstream consumer.</p>

        <ul>
          <li>Paddle signs each delivery with the `Paddle-Signature` header using an HMAC-SHA256 signature computed with the notification setting's endpoint secret key.</li>
          <li>StackOne responds with `200 OK` automatically for all recognised events.</li>
          <li>Paddle retries failed deliveries if the endpoint does not return a `2xx` response.</li>
        </ul>
      </div>
    </Step>

    <Step title="Unsubscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Disconnecting the account or removing all event subscriptions deletes the StackOne-managed notification setting in Paddle, stopping all event deliveries.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available Webhook Events</h2>

  <p>The following Paddle events can be enabled. Only events selected in StackOne are included in the subscription.</p>

  <Steps>
    <Step title="Address events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to customer address lifecycle.</p>

        <ul>
          <li><strong>Address Created</strong> (`address.created`) — Fired when a new address is created on a customer account</li>
          <li><strong>Address Imported</strong> (`address.imported`) — Fired when an address is imported</li>
          <li><strong>Address Updated</strong> (`address.updated`) — Fired when an address is updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Adjustment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to refunds, credits, and chargebacks.</p>

        <ul>
          <li><strong>Adjustment Created</strong> (`adjustment.created`) — Fired when a new adjustment is created for a transaction</li>
          <li><strong>Adjustment Updated</strong> (`adjustment.updated`) — Fired when an adjustment status changes</li>
        </ul>
      </div>
    </Step>

    <Step title="API key events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to API key lifecycle.</p>

        <ul>
          <li><strong>API Key Created</strong> (`api_key.created`) — Fired when a new API key is created</li>
          <li><strong>API Key Expired</strong> (`api_key.expired`) — Fired when an API key reaches its expiration date</li>
          <li><strong>API Key Expiring</strong> (`api_key.expiring`) — Fired shortly before an API key expires</li>
          <li><strong>API Key Revoked</strong> (`api_key.revoked`) — Fired when an API key is manually revoked</li>
          <li><strong>API Key Updated</strong> (`api_key.updated`) — Fired when an API key's properties are updated</li>
          <li><strong>API Key Exposure Created</strong> (`api_key_exposure.created`) — Fired when a potential API key exposure is detected</li>
        </ul>
      </div>
    </Step>

    <Step title="Business events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to business entity lifecycle on customer accounts.</p>

        <ul>
          <li><strong>Business Created</strong> (`business.created`) — Fired when a new business entity is created</li>
          <li><strong>Business Imported</strong> (`business.imported`) — Fired when a business entity is imported</li>
          <li><strong>Business Updated</strong> (`business.updated`) — Fired when a business entity is updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Client token events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to client-side token lifecycle.</p>

        <ul>
          <li><strong>Client Token Created</strong> (`client_token.created`) — Fired when a new client token is created</li>
          <li><strong>Client Token Revoked</strong> (`client_token.revoked`) — Fired when a client token is revoked</li>
          <li><strong>Client Token Updated</strong> (`client_token.updated`) — Fired when a client token is updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Customer events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to customer lifecycle.</p>

        <ul>
          <li><strong>Customer Created</strong> (`customer.created`) — Fired when a new customer is created</li>
          <li><strong>Customer Imported</strong> (`customer.imported`) — Fired when a customer is imported</li>
          <li><strong>Customer Updated</strong> (`customer.updated`) — Fired when a customer's details are updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Discount events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to discount coupon and group lifecycle.</p>

        <ul>
          <li><strong>Discount Created</strong> (`discount.created`) — Fired when a new discount is created</li>
          <li><strong>Discount Imported</strong> (`discount.imported`) — Fired when a discount is imported</li>
          <li><strong>Discount Updated</strong> (`discount.updated`) — Fired when a discount's properties are updated</li>
          <li><strong>Discount Group Created</strong> (`discount_group.created`) — Fired when a new discount group is created</li>
          <li><strong>Discount Group Updated</strong> (`discount_group.updated`) — Fired when a discount group is updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Payment method events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to saved payment methods on customer accounts.</p>

        <ul>
          <li><strong>Payment Method Saved</strong> (`payment_method.saved`) — Fired when a payment method is saved to a customer account</li>
          <li><strong>Payment Method Deleted</strong> (`payment_method.deleted`) — Fired when a payment method is removed from a customer account</li>
        </ul>
      </div>
    </Step>

    <Step title="Payout events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to seller payouts.</p>

        <ul>
          <li><strong>Payout Created</strong> (`payout.created`) — Fired when a new payout is created</li>
          <li><strong>Payout Paid</strong> (`payout.paid`) — Fired when a payout is successfully sent to the seller's bank account</li>
        </ul>
      </div>
    </Step>

    <Step title="Price events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to product price lifecycle.</p>

        <ul>
          <li><strong>Price Created</strong> (`price.created`) — Fired when a new price is created for a product</li>
          <li><strong>Price Imported</strong> (`price.imported`) — Fired when a price is imported</li>
          <li><strong>Price Updated</strong> (`price.updated`) — Fired when a price's properties are updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Product events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to product catalog lifecycle.</p>

        <ul>
          <li><strong>Product Created</strong> (`product.created`) — Fired when a new product is created in the catalog</li>
          <li><strong>Product Imported</strong> (`product.imported`) — Fired when a product is imported</li>
          <li><strong>Product Updated</strong> (`product.updated`) — Fired when a product's properties are updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Report events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to report generation.</p>

        <ul>
          <li><strong>Report Created</strong> (`report.created`) — Fired when a new report is created</li>
          <li><strong>Report Updated</strong> (`report.updated`) — Fired when a report's status changes (e.g., becomes ready for download)</li>
        </ul>
      </div>
    </Step>

    <Step title="Subscription events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to subscription lifecycle.</p>

        <ul>
          <li><strong>Subscription Activated</strong> (`subscription.activated`) — Fired when a subscription becomes active</li>
          <li><strong>Subscription Canceled</strong> (`subscription.canceled`) — Fired when a subscription is canceled</li>
          <li><strong>Subscription Created</strong> (`subscription.created`) — Fired when a new subscription is created</li>
          <li><strong>Subscription Imported</strong> (`subscription.imported`) — Fired when a subscription is imported</li>
          <li><strong>Subscription Past Due</strong> (`subscription.past_due`) — Fired when a subscription payment fails and enters past due status</li>
          <li><strong>Subscription Paused</strong> (`subscription.paused`) — Fired when a subscription is paused</li>
          <li><strong>Subscription Resumed</strong> (`subscription.resumed`) — Fired when a paused subscription is resumed</li>
          <li><strong>Subscription Trialing</strong> (`subscription.trialing`) — Fired when a subscription enters a trial period</li>
          <li><strong>Subscription Updated</strong> (`subscription.updated`) — Fired when a subscription's properties are updated</li>
        </ul>
      </div>
    </Step>

    <Step title="Transaction events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to transaction lifecycle and payment processing.</p>

        <ul>
          <li><strong>Transaction Billed</strong> (`transaction.billed`) — Fired when a transaction is billed and an invoice is issued</li>
          <li><strong>Transaction Canceled</strong> (`transaction.canceled`) — Fired when a transaction is canceled</li>
          <li><strong>Transaction Completed</strong> (`transaction.completed`) — Fired when a transaction is fully completed</li>
          <li><strong>Transaction Created</strong> (`transaction.created`) — Fired when a new transaction is created</li>
          <li><strong>Transaction Paid</strong> (`transaction.paid`) — Fired when payment is successfully collected</li>
          <li><strong>Transaction Past Due</strong> (`transaction.past_due`) — Fired when a transaction passes its due date without payment</li>
          <li><strong>Transaction Payment Failed</strong> (`transaction.payment_failed`) — Fired when a payment attempt fails</li>
          <li><strong>Transaction Ready</strong> (`transaction.ready`) — Fired when a transaction is ready for payment</li>
          <li><strong>Transaction Revised</strong> (`transaction.revised`) — Fired when a completed transaction is revised</li>
          <li><strong>Transaction Updated</strong> (`transaction.updated`) — Fired when a transaction's details are updated</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.