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 — You can then specify a number of custom fields that are sent along with the request.

In addition to any custom fields you define, we also send the following default parameters:

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)

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
currency string(3) The three letter ISO currency code. Eg: USD, GBP
earnings decimal The amount of this payment that was credited to your balance.
fee decimal The fee charged by Paddle for this payment.
email string The email address of the customer this payment is from.
sale_gross decimal The total amount this payment was for.
payment_tax decimal The amount of this payment that was paid in tax/VAT.
passthrough string This field contains any values that you passed into the checkout using the ‘passthrough’ parameter. (See: Checkout Documentation)
country string(2) The two letter ISO country code of the customer. Eg: US, GB
order_id int(11) The Paddle Order ID for this payments. This can be used to lookup the order 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)

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.  
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.
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.
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)
Was this page helpful?