Using Webhooks

Webhooks are HTTP calls to your server that make it super easy for Paddle to communicate data and events to your server, 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, the second type of webhook is a fulfilment webhook, this is a webhook thats 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
currency string(3) The three letter ISO currency code. Eg: USD, GBP
amount decimal The amount this refund is for.
email string The email address of the customer this refund is being sent to.
order_id int(11) Ther Paddle Order ID that is being refund. This can be used to lookup the order within your Paddle account.
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
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)

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)

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?
Yes or No