Fill in the form to arrange a demo

Using Webhooks

Webhooks are HTTP calls to your server that make it really easy for you to receive data and events from Paddle, and for your server to communicate data back.

There are two distinct instances in which webhooks are used within Paddle:

  • As an event or alert which you subscribe to within the ‘Alerts’ tab of your Paddle Dashboard - for example upon a successful payment or a balance transfer to your bank account.
  • As a fulfillment webhook: this is a webhook used during order processing, usually to allow you to pass information (such as a license code) back to Paddle - that is then sent to the customer.

Subscribing to Alerts

Before you receive any events, you need to define the URL that we should send the HTTP POST requests to.

  • Step 1: Visit the Alerts / Webhooks page in your Paddle dashboard
  • Step 2: Check each alert that you wish to receive a notification for.
  • Step 3: If you’re receiving webhook alerts enter a URL that we should send the HTTP POST requests to at the bottom of the page.
  • Step 4: Click the “Save Changes” button to confirm your alerts.

List of Alerts

Note: A list of alerts/events that are sent during the course of a subscription can be found here, whereas the list below are other (non-subscription) events that you can subscribe to within the Alerts / Webhooks page in your Paddle dashboard.

Below is a list of non-subscription events that you can subscribe to. To identify the event you’re being sent, use the HTTP POST parameter named alert_name which will contain the Event Name.

Event Parameters Description
locker_processed Fields Fired when an order is created after a successful payment event.
payment_succeeded Fields Fired when a payment is made into your Paddle account.
payment_refunded Fields Fired when a payment is refunded.
high_risk_transaction_created Fields Fired when a transaction is flagged as high risk.
high_risk_transaction_updated Fields Fired when a flagged transaction is approved or rejected.
payment_dispute_created Fields Fired when a dispute/chargeback is created for one of your transactions.
payment_dispute_closed Fields Fired when a dispute/chargeback is closed or completed for one of your transactions.
transfer_created Fields Fired when a new transfer/payout is created for your account.
transfer_paid Fields Fired when a new transfer/payout is marked as paid for your account. (This usually happens the day before the money credits your bank account)
new_audience_member Fields Fired when a customer opts in to receive marketing communication from you.
update_audience_member Fields Fired when the information of an audience member is updated.

Fulfillment Webhooks

As above, the second type of webhook Paddle sends are those used during order processing, this is typically used to send order-specific data to a customer after the payment process. For example generating a license code for activating a piece of software that is sent to the customer after an order.

The response from the fulfillment webhook is emailed to the customer as part of the order process. (Note: Emailing can be disabled when you’re editing your product from within the dashboard)

Setting Up a Fulfillment Webhook Fulfillment webhooks are product specific (unlike the Alerts/Events which are account-wide) and you set them up during product creation. Simply set the fulfillment method to “Webhook” or “Send a HTTP Request to my Server” during product creation or while editing.

Once setup, on the product ‘Release Checklist’ you can visit the ‘Webhook Editor’, you should see a page that looks similar to the one below:

webhook-setup

On this page, you can fill out the fields to tell us what data to send to your webhook about the order, and in what format, the fields available are:

  • Webhook URL — The URL that we will send the HTTP request to.
  • Request Method — The HTTP request method. (Either GET or POST)
  • Instructions — Some text that will be sent along with the response from your webhook to the customer. Particularly useful for including something like activation instructions along with a license code, for example.
  • Separate Multibuy — For quantity orders, should we send a single webhook request with a quantity attribute. Or a webhook request for each quantity item.
  • Custom Fields — In addition to the standard fields below, you may optionally send the checkout hash, transaction ID, customer email, customer name (if collected) or a static value or message.

We send the following default parameters with each fulfillment webhook:

Field Type/Format Description
p_quantity int(11) The number of items ordered.
p_coupon_savings decimal The amount of savings given by the applied coupon.
p_country string(2) The two letter ISO country code of the customer. Eg: US, GB
p_coupon string The coupon code that was used on this checkout.
p_tax_amount decimal The amount of this order that was paid in tax.
p_currency string(3) The three letter ISO currency code. Eg: USD, GBP
p_paddle_fee decimal The amount of this order that was paid to Paddle as a fee.
p_price decimal The price the user paid for this order.
p_order_id int(11) The Paddle order ID. You can use this to lookup the order within the Paddle Dashboard.
p_earnings JSON String This contains the amount credited to your balance. It is returned as an array in the format: vendor_id => earnings_amount. This array will contain multiple values if there is more than one account involved in the purchase (for example a split-checkout).
p_product_id int(11) The Paddle ID of the product that was purchased.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)
marketing_consent int(11) This is an optional field whose value (0 or 1) indicates whether the customer has provided consent to receive marketing messages from the vendor
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time the fulfillment webhook was sent.

Responding to Webhooks

For webhook events/ alerts, your server should respond with a HTTP 200 status code to indicate you have successfully received the message. If we receive anything other than a HTTP 200 we will retry the call to your webhook URL every hour for a maximum of 72 hours.


Locker Processed

Identify this event with the HTTP POST parameter alert_name with a value of locker_processed

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string locker_processed
checkout_id string The checkout id of the order created.
checkout_recovery int(11) The value of this field “1” or “0” indicates whether the order originated from a checkout recovery email.
coupon string The coupon code that was used on this order.
download string The download URL of the purchased product.
email string The email address of the customer for the order created.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time the order has been created.
instructions string The instructions details that has been sent to the customer.
license string The license number associated with the order (when applicable).
marketing_consent int(11) The value of this field “1” or “0” indicates whether the customer has agreed to receive marketing messages from the vendor.
order_id int(11) The Paddle Order ID, this can be used to look up the order within your Paddle Dashboard.
product_id int(11) The dashboard ID of the product purchased in this order.
quantity string The number of products purchased in this order.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Payment Succeeded

Identify this event with the HTTP POST parameter alert_name with a value of payment_succeeded

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string payment_succeeded
balance_currency decimal Your dashboard balance currency.
balance_earnings decimal The amount credited to your balance in your default currency.
balance_fee decimal The fees taken by Paddle in your dashboard balance currency.
balance_gross decimal The sale value in your dashboard balance currency.
balance_tax decimal The amount paid in tax in your dashboard balance currency.
checkout_id string The checkout id of the transaction
country string(2) The two letter ISO country code of the customer. Eg: US, GB
coupon string The coupon code, if used for the transaction.
currency string(3) The three letter ISO currency code. Eg: USD, GBP
customer_name string The name of the customer this payment is from (if collected).
earnings decimal The amount of this payment that was credited to your balance.
email string The email address of the customer this payment is from.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this payment succeeded.
fee decimal The fee taken by Paddle for this payment.
ip string The IP address of the customer.
marketing_consent int(11) The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
order_id int(11) The Paddle Order ID for this payment. This can be used to look up the order within your Paddle Dashboard.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
payment_method string The method used for payment (apple-pay, card, free, paypal, wire-transfer).
payment_tax decimal The amount of this payment that was paid in tax/VAT.
product_id integer The Paddle ID of the product that was purchased.
product_name string The name of the product included in the transaction.
quantity string The number of products sold in the transaction.
receipt_url string A URL where the receipt for the transaction can be retrieved.
sale_gross decimal The total value of the sale (including tax) in the sale currency.
used_price_override string Whether the dashboard price was overridden (true or false).
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Payment Refunded

Identify this event with the HTTP POST parameter alert_name with a value of payment_refunded

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string payment_refunded
amount decimal The amount refunded, partial refunds are possible.
balance_currency  string(3)    The three letter ISO currency code of the vendor’s default currency at the time of the transaction. Eg: USD, GBP. 
balance_earnings_decrease decimal      The amount of revenue taken from the vendor’s earnings as a result of this refund, in the vendor’s default currency at the time of the transaction.  It returns a positive or negative value. Eg: If you issue a VAT only refund, this will increase the vendor’s earnings instead of decreasing it, to reflect this we use a negative value. Please also note that if the earnings of the order being refunded are being split between vendors, the earnings decrease amount will not include the other vendor’s fee, only yours. (eg. If you are giving 15% of your earnings to another vendor and keeping 85%, your balance earnings will be reduced only by 85%).
balance_fee_refund  decimal      The fee amount returned to the vendor, in the vendor’s default currency at the time of the transaction. 
balance_gross_refund decimal      The total amount returned to the customer as a result of this refund, in the vendor’s default currency at the time of the transaction.
balance_tax_refund  decimal      The amount of tax returned to the customer, in the vendor’s default currency at the time of the transaction. 
checkout_id string The checkout id of the transaction being refunded.
currency string(3) The three letter ISO currency code of the transaction. Eg: USD, GBP
earnings_decrease  decimal      The amount of revenue taken from the vendor’s earnings as a result of this refund, in the currency of the original transaction. It returns a positive or negative value. E.g: if you issue a VAT only refund, this will increase the vendor’s earnings instead of decreasing it, to reflect this we use a negative value. Please also note that if the earnings of the order being refunded are being split between vendors, the earnings decrease amount will not include the other vendor’s fee, only yours: for example if you are giving 15% of your earnings to another vendor and keeping 85%, your balance earnings will only be reduced by 85%. 
email string The email address of the customer this refund is being sent to.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this refund was issued.
fee_refund     decimal      The fee amount returned to the vendor, in the currency of the original transaction.
gross_refund   decimal      The total amount returned to the customer as a result of this refund, in the currency of the original transaction. 
marketing_consent int(11) The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
order_id int(11) The Paddle Order ID that is being refunded. This can be used to lookup the order within your Paddle account.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
quantity string The number of products sold in the transaction.
refund_type string The type of refund, the value of this field can be full, vat or partial.
tax_refund     decimal      The amount of tax returned to the customer, in the currency of the original transaction. 
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

High Risk Transaction Created

Identify this event with the HTTP POST parameter alert_name with a value of high_risk_transaction_created

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string high_risk_transaction_created
case_id int(11) The case id for the flagged order.
checkout_id string The checkout id of the flagged order.
created_at UTC datetime (yyyy-mm-dd HH:mm:ss) Date and time this order was flagged.
customer_email_address string The email address of the customer for the flagged order.
customer_user_id int(11) The Paddle user id associated with this customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) Date and time this order was flagged.
marketing_consent int(11) The value of this field “1” or “0” indicates whether the customer has agreed to receive marketing messages from the vendor.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
product_id int(11) The Paddle ID of the product that was purchased.
risk_score decimal The risk value associated with the order ranging from 0.10 to 99.99; a higher value indicates a higher chance of the order being fraudulent.
status string The status of the order; it will always be pending for flagged orders.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

High Risk Transaction Updated

Identify this event with the HTTP POST parameter alert_name with a value of high_risk_transaction_updated

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string high_risk_transaction_updated
case_id int(11) The case id for the flagged order.
checkout_id string The checkout id of the flagged order.
created_at UTC datetime (yyyy-mm-dd HH:mm:ss) Date and time this order was flagged.
customer_email_address string The email address of the customer for the flagged order.
customer_user_id int(11) The Paddle user id associated with this customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) Date and time the flagged order’s status was updated.
marketing_consent int(11) The value of this field “1” or “0” indicates whether the customer has agreed to receive marketing messages from the vendor.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. See the Paddle Checkout (Web) documentation for more information.
product_id int(11) The Paddle ID of the product that was purchased.
risk_score decimal The risk value associated with the order ranging from 0.10 to 99.99; a higher value indicates a higher chance of the order being fraudulent.
status string Status of the flagged order; it can have the following values: accepted or rejected
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Payment Dispute Created

Identify this event with the HTTP POST parameter alert_name with a value of payment_dispute_created

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string payment_dispute_created
amount decimal The amount of the transaction in-dispute.
checkout_id string The checkout id of the transaction being disputed.
currency string(3) The three letter ISO currency code. Eg: USD, GBP
email string The email of the customer who lodged the dispute.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this payment was disputed.
fee_usd decimal The fee you were charged for this dispute (in USD).
marketing_consent int(11) The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
order_id string The Paddle Order ID for this payment. This can be used to look up the order within your Paddle Dashboard.
status string The status of this dispute; it will always be open when created
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Payment Dispute Closed

Identify this event with the HTTP POST parameter alert_name with a value of payment_dispute_closed

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string payment_dispute_closed
amount decimal The amount of the dispute.
checkout_id string The checkout id of the transaction being disputed.
currency string(3) The three letter ISO currency code. Eg: USD, GBP
email string The email of the customer who lodged the dispute.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this dispute was closed.
fee_usd decimal The fee you were refunded for this dispute being closed (in USD).
marketing_consent int(11) The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
order_id string The Paddle Order ID for this payment. This can be used to look up the order within your Paddle Dashboard.
status string The status of this dispute; it will always be closed when resolved
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Transfer Created

Identify this event with the HTTP POST parameter alert_name with a value of transfer_created

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string transfer_created
amount decimal The amount of the payout.
currency string(3) The three letter ISO currency code. Eg: USD, GBP
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this payout was created.
payout_id int(11) The ID of the payout. Can be used to lookup the payout within your Paddle Dashboard.
status string The payout status; it will always be unpaid when created.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Transfer Paid

Identify this event with the HTTP POST parameter alert_name with a value of transfer_paid

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string transfer_paid
amount decimal The amount of the payout.
currency string(3) The three letter ISO currency code. Eg: USD, GBP
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time this payout was marked as paid.
payout_id int(11) The ID of the payout. Can be used to lookup the payout within your Paddle Dashboard.
status string The payout status; it will always be paid when completed.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

New Audience Member

Identify this event with the HTTP POST parameter alert_name with a value of new_audience_member

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string new_audience_member
created_at UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time the customer has been added.
email string The email address of the customer.
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time the customer has been added.
marketing_consent int(11) The value will be “1” for customers that have provided consent to be contacted with marketing messages and “0” for those that have not provided consent.
products JSON String It is returned an array with the Paddle IDs of the products the customer has purchased.
source string Source of customer acquisition; it can have one of the following values: Checkout,Trial,Order,Activation, Import or Application.
subscribed int(11) The value will be “1” for customers that have subscribed to marketing messages and “0” for those that have not subscribed.
user_id int(11) The Paddle user id associated with this customer.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Update Audience Member

Identify this event with the HTTP POST parameter alert_name with a value of update_audience_member

Fields: Each of the below are HTTP POST fields sent with this event.

Field Type/Format Description
alert_name string update_audience_member
event_time UTC datetime (yyyy-mm-dd HH:mm:ss) The date and time the update was made.
new_customer_email string The customer’s new email address.
new_marketing_consent int(11) The new marketing consent which will be “0” or “1” depending on whether the customer has provided consent to be contacted with marketing messages.
old_customer_email string The customer’s previous email address.
old_marketing_consent int(11) The previous marketing consent which will be “0” or “1” depending on whether the customer has provided consent to be contacted with marketing messages.
products JSON String An array with the Paddle IDs of the products the customer has purchased.
source string Source of customer acquisition; it can have one of the following values: Checkout,Trial,Order,Activation,Import or Application
updated_at UTC datetime (yyyy-mm-dd HH:mm:ss) Date and time this update occurred.
user_id int(11) The Paddle user id associated with this customer.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

Next Steps

Subscriptions Event Reference
The easiest way to keep your system in sync with Paddle is by subscribing to webhooks. We send a HTTP POST request to your webhook endpoint for each action against a subscription (such as a subscription payment, plan change, cancellation).

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.

Questions about Paddle?