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 fulfilment 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.

Alert / Event Webhooks

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 your Account Settings page in the Vendor Dashboard.
  • Step 2: Click the “Alerts” tab at the top of the page.
  • Step 3: Check each alert that you wish to receive a notification for.
  • Step 4: 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 5: Click the “Save Changes” button to confirm your alerts.

List of Alerts A reference of alerts/ events that are sent during the course of a subscription can be found here, the list below are the other (non-subscription) events that you can subscribe to within the Alerts tab of your Paddle dashboard.

Event Parameters Description
payment_succeeded Fields Fired when a payment is made into your Paddle account.
payment_refunded Fields Fired when a payment is refunded.
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)

Fulfilment 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 fulfilment 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 Fulfilment Webhook Fulfilment webhooks are product specific (unlike the Alerts/Events which are account-wide) and you set them up during product creation. Simply set the fulfilment 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 fulfilment 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: Checkout Documentation)
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)
marketing_consent string This is an optional field whose value (0 or 1) indicates whether the customer has provided consent to receive marketing messages from the vendor

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.


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
checkout_id string The checkout id of the transaction
order_id int(11) The Paddle Order ID for this payment. This can be used to look up the order within your Paddle Dashboard.
currency string(3) The three letter ISO currency code. Eg: USD, GBP
sale_gross decimal The total value of the sale (including tax) in the sale currency.
payment_tax decimal The amount of this payment that was paid in tax/VAT.
fee decimal The fee taken by Paddle for this payment.
earnings decimal The amount of this payment that was credited to your balance.
balance_currency decimal 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.
balance_fee decimal The fees taken by Paddle in your dashboard balance currency.
balance_earnings decimal The amount credited to your balance in your default currency.
coupon string The coupon code, if used for the transaction.
payment_method string The method used for payment e.g. card.
used_price_override string Whether the dashboard price was overridden (true or false).
email string The email address of the customer this payment is from.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
customer_name string The name of the customer this payment is from (if collected).
ip string The IP address of the customer.
country string(2) The two letter ISO country code of the customer. Eg: US, GB
product_name string The name of the product included in the transaction.
product_id integer The dashboard ID 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.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. (See: Checkout Documentation)
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.  
checkout_id int(11) The checkout id of the transaction being refunded.  
currency string(3) The three letter ISO currency code of the transaction. Eg: USD, GBP  
email string The email address of the customer this refund is being sent to.  
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.  
event_time datetime (yyyy-mm-dd HH:mm:ss) The date and time this refund was issued.  
instalments int Number of payments made by the customer to date.  
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: Checkout Documentation)  
user_id int(11) The customer user id.  
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)  
gross_refund   decimal      The total amount returned to the customer as a result of this refund, in the currency of the original transaction.   
tax_refund     decimal      The amount of tax returned to the customer, in the currency of the original transaction.   
fee_refund     decimal      The fee amount returned to the vendor, in the currency of the original transaction.  
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%.   
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_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.   
balance_fee_refund  decimal      The fee amount returned to the vendor, in the vendor’s default currency at the time of the transaction.   
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%).  

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
currency string(3) The three letter ISO currency code. Eg: USD, GBP
status string The status of this dispute. (open/closed)
fee_usd decimal The fee you were charged for this dispute (in USD).
amount decimal The amount of the transaction in-dispute.
email string The email of the customer who lodged the dispute.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)
checkout_id int(11) The checkout id of the transaction being disputed.

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
currency string(3) The three letter ISO currency code. Eg: USD, GBP
status string The status of this dispute. (open/closed)
fee_usd decimal The fee you were refunded for this dispute being closed (in USD).
amount decimal The amount of the dispute.
email string The email of the customer who lodged the dispute.
marketing_consent string The value of this field “1” or “0” indicates whether the user has agreed to receive marketing messages from the vendor.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)
checkout_id int(11) The checkout id of the transaction being disputed.

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
currency string(3) The three letter ISO currency code. Eg: USD, GBP
status string The payout status. (paid/unpaid)
amount decimal The amount of the payout.
payout_id int(11) The ID of the payout. Can be used to lookup the payout within your Paddle Dashboard.
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
currency string(3) The three letter ISO currency code. Eg: USD, GBP
status string The payout status. (paid/unpaid)
amount decimal The amount of the payout.
payout_id int(11) The ID of the payout. Can be used to lookup the payout within your Paddle Dashboard.
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 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 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 the customers that have provided consent to be contacted with marketing messages and “0” for the ones 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 How the customer has been aquired, it can have the following values Checkout,Trial,Order,Activation, Import or Application.
updated_at datetime (yyyy-mm-dd HH:mm:ss) Date and time the user has been added.
user_id int(11) The customer user id.
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 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 the following values Checkout,Trial,Order,Activation,Import or Application
updated_at datetime (yyyy-mm-dd HH:mm:ss) Date and time this update ocurred.
user_id int(11) The customer user id.
p_signature string This field contains an encrypted token that you can use to verify the request authenticity. (See: Verifying Webhooks)

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.