Using webhook notifications

ThriveCart supports the delivery of webhook notifications for a number of events.

We will send an HTTP POST request to the target URL(s) that you have set up under Settings > API & Webhooks > Webhooks & notifications. You can take the data sent to your custom script and handle that to do whatever you’d like.

Your script must respond with an HTTP 2xx status code for both a POST and HEAD request, otherwise, we will not allow you to add it.

We also have a separate ThriveCart API for advanced developers over at developers.thrivecart.com

1. Setting up a webhook

Your webhook must be accessible via the internet and it must return a 2xx HTTP status code when we ping it with either a HEAD or a POST request.

These webhooks are a ‘catch all’ type system where your script will receive data for all events for all products in your account. It will be the job of your script to then filter based on the events and specific products.

You can add up to 5 webhooks destination URLs in total (if you require more, you can get in touch with us and request raising this limit providing the reason why you need more).

From your ThriveCart account, head to your Settings > API & Webhooks > Webhooks area.

You can enter a descriptive name for your Webhook (this will be populated in a list once you’ve created your first) and the URL to POST to.

We will ping the URL and check that it is functioning, and then add it. Once added, it will become immediately active, and notifications will start to be sent there as they trigger in ThriveCart.

2. Testing the webhook

After you’ve added your webhook URL into ThriveCart, we’ll start to send notifications about all transactions in your account. This includes those for products in test mode.

Your script can be set up to listen for these events and record the data that’s sent to it. The data can vary based on how your checkout is set up. Some information may be different from checkout to checkout, based on your cart settings, so it’s worth testing and checking the data.

You can also use 3rd-party services like webhook.site. This service will provide you with a URL you can add to ThriveCart. It will then log all transactions processed and break down the data so you can easily review it.

If you’re wanting to test different types of webhook events, then you will typically want to ensure you have Stripe set up as a payment processor, then use the test mode of your product. You can complete orders through your funnel and then pull up the test mode payments and handle things like refunds, managing subscriptions, etc, to trigger the various events.

See this article on testing your funnels.

3. Verifying the webhook

As part of the parameters that we provide, we include a thrivecart_secret parameter. This is a string that will match up with the ‘Secret word’ that can be found under your Settings > API & Webhooks > ThriveCart order validation area in your account.

You should hard-code this at your end and ensure that it matches up with what we provide to ensure nobody else is posting to your URL.

Webhook Parameters

The following parameters are included in our notifications.

Please note that this is not a definitive list, as parameters may vary based on the checkout setup.

Note that any and all keys representing prices are in hundreds, as standard. So if a customer was charged $14.99, we would provide you with 1499. You can divide these integers by 100 to get the amount in dollars and cents.

We also include amount_str which is in a currency format. So we also pass through 14.99 as well as 1499, giving you easier options and more choice in how you use the data sent to you.

We send the data through as POST variables as key/value pairs, and in these, we do have nested variables that create objects/arrays when decoded.

event: string (order.success)

thrivecart_account: string (Your account's subdomain)

thrivecart_secret: string (Your account's 'secret word' parameter)

base_product: int (The ID of the front-end product this order relates to)

order_id: int (Unique order ID)

currency: string (Uppercase, 3-character currency code - USD, GBP, etc)

customer_id: int (Customer ID)

customer_identifier: string (Customer identifier from your payment processor - may be null)

customer: array (name, firstname, lastname, email, address)

order: array:
  tax: int (Amount of tax charged)
  tax_type: string (au-gst, nz-gst, gb, fr, us-tx, etc)
  processor: string (stripe/paypal)
  total: int (Total amount charged)
  charges: array (type, name, reference, amount, frequency)
  future_charges: array (type, name, reference, amount, frequency, due)

purchases: array (Array of the names of all purchases, including the front-end, bump, upsell(s)/downsell(s))

purchase_map: array (Array containing purchases; for example, product-12, bump-12, upsell-2, upsell-3, downsell-5)

purchase_map_flat: string (A string containing the above info concatenated into a single string: "product-12, bump-12, upsell-2")

fulfillment: array (id, hash, url. The URL links to the confirmation page that the customer was taken to after ordering)

As well as the above, we also include any passthrough variables you send through the checkout in the webhook data.

It may be worth catching all data at the start to see what’s sent to you, or to use that webhook.site example noted above to see the data from events from your account.

Webhook events

There are multiple events that are sent out by ThriveCart. You can see these below.

• order.success
• order.refund
• cart.abandoned
• order.subscription_payment
• order.subscription_cancelled
• order.subscription_paused
• order.subscription_resumed
• order.rebill_failed
• affiliate.commission_earned
• affiliate.commission_payout
• affiliate.commission_refund

Debugging your webhook

Webhooks are x-www-form-urlencoded

Data is POST-ed over as multipart form values. In PHP for example, that’s done through the $_POST superglobal.

They are sent for test sales (they will contain a key mode which is either live or test, and also mode_int which is either 2 (live) or 1 (test).

If you are trying to add a webhook but it is displaying an error, or if you’ve added your webhook but you aren’t receiving the results you expect, the problem is almost certainly on your side.

Before contacting support, please make sure that you have confirmed that your script returns an HTTP 2xx response for a HEAD request and for a POST request and that you have debugged the script itself to ensure it works as expected.

Tools like Postman can be useful for sending requests to a URL, and you may find it useful to create a Requestbin and add its URL into our webhooks section so that you can capture some example results to use.

Please ensure that you have checked this out thoroughly before reaching out to us because in 99% of cases, the problem lies within your custom script, which we won’t be able to diagnose for you!

The only thing our team will be able to verify is if the request was made, and what the response from the script was.

Let’s look at some example events and data!

Here’s an order.success example (for a subscription).

Here’s a copy of the event that would be passed through to your script:

event=order.success&mode=test&mode_int=1&thrivecart_account=generic&thrivecart_secret=JLZE3Y54FEQ1&base_product=2&order_id=1514394&invoice_id=000000004&order_date=2019-03-06%2022%3A57%3A24&order_timestamp=1551913044&currency=USD&customer_id=6702306&customer_identifier=cus_EeRXonHQ7LQPBQ&customer%5Bid%5D=6702306&customer%5Bemail%5D=jsmith%40email.com&customer%5Baddress%5D%5Bcountry%5D=NZ&customer%5Baddress%5D%5Bstate%5D=Bay%20of%20Plenty&customer%5Baddress%5D%5Bline1%5D=1234%20Main%20Street&customer%5Baddress%5D%5Bcity%5D=Auckland&customer%5Baddress%5D%5Bzip%5D=3345&customer%5Bip_address%5D=255.255.255.255&customer%5Bname%5D=John%20Smith&customer%5Bcheckbox_confirmation%5D=false&customer%5Bfirst_name%5D=John&customer%5Blast_name%5D=Smith&order%5Btax%5D=null&order%5Btax_type%5D=null&order%5Bprocessor%5D=stripe&order%5Btotal%5D=10000&order%5Btotal_str%5D=100.00&order%5Bcharges%5D%5B0%5D%5Bname%5D=Webhook%20testing&order%5Bcharges%5D%5B0%5D%5Breference%5D=2&order%5Bcharges%5D%5B0%5D%5Bitem_type%5D=product&order%5Bcharges%5D%5B0%5D%5Bitem_identifier%5D=product_2&order%5Bcharges%5D%5B0%5D%5Bamount%5D=10000&order%5Bcharges%5D%5B0%5D%5Bamount_str%5D=100.00&order%5Bcharges%5D%5B0%5D%5Btype%5D=single&order%5Bcharges%5D%5B0%5D%5Bquantity%5D=1&order%5Bcharges%5D%5B0%5D%5Bpayment_plan_id%5D=17869&order%5Bcharges%5D%5B0%5D%5Bpayment_plan_name%5D=Subscription%20%28%24100.00%2Fmnth%29&order%5Bcharges%5D%5B1%5D%5Bname%5D=Webhook%20testing&order%5Bcharges%5D%5B1%5D%5Breference%5D=2&order%5Bcharges%5D%5B1%5D%5Bitem_type%5D=product&order%5Bcharges%5D%5B1%5D%5Bitem_identifier%5D=product_2&order%5Bcharges%5D%5B1%5D%5Bamount%5D=10000&order%5Bcharges%5D%5B1%5D%5Bamount_str%5D=100.00&order%5Bcharges%5D%5B1%5D%5Btype%5D=recurring&order%5Bcharges%5D%5B1%5D%5Bquantity%5D=1&order%5Bcharges%5D%5B1%5D%5Bfrequency%5D=month&order%5Bcharges%5D%5B1%5D%5Bpayment_plan_id%5D=17869&order%5Bcharges%5D%5B1%5D%5Bpayment_plan_name%5D=Subscription%20%28%24100.00%2Fmnth%29&order%5Bdate%5D=2019-03-06%2022%3A57%3A25&order%5Bdate_unix%5D=1551913045&transactions%5Bproduct-2%5D=ch_1EB8ftAB5gsRjJxz4wuVM65M&subscriptions%5Bproduct-2%5D=sub_EeRZvC1TxlYaT7&purchases%5B0%5D=Webhook%20testing&purchase_map%5B0%5D=product-2&purchase_map_flat=product-2&fulfillment%5Burl%5D=https%3A%2F%2Fgeneric.thrivecart.com%2Fwebhook-testing%2Fconfirm%2F%2F

Here’s an order.subscription_payment example.

event=order.subscription_payment&mode=test&mode_int=1&thrivecart_account=generic&thrivecart_secret=JLZE3Y55THL2&base_product=2&order_id=1514394&invoice_id=000000004-2&recurring_payment_idx=2&currency=USD&customer_id=6702306&customer%5Bid%5D=6702306&customer%5Bemail%5D=jsmith%40email.com&customer%5Baddress%5D%5Bcountry%5D=NZ&customer%5Baddress%5D%5Bstate%5D=Bay%20of%20Plenty&customer%5Baddress%5D%5Bline1%5D=1234%20Main%20Street&customer%5Baddress%5D%5Bcity%5D=Auckland&customer%5Baddress%5D%5Bzip%5D=3345&customer%5Bip_address%5D=255.255.255.255&customer%5Bname%5D=John%20Smith&customer%5Bcheckbox_confirmation%5D=false&customer%5Bfirst_name%5D=John&customer%5Blast_name%5D=Smith&order%5Btax%5D=null&order%5Btax_type%5D=null&order%5Bprocessor%5D=stripe&order%5Btotal%5D=10000&order%5Btotal_str%5D=100.00&subscription%5Btype%5D=product&subscription%5Bid%5D=2&subscription%5Bname%5D=Webhook%20testing&subscription%5Bprocessor%5D=stripe&subscription%5Bamount%5D=10000&subscription%5Bamount_str%5D=100.00

Here’s an order.subscription_cancelled example.

event=order.subscription_cancelled&mode=test&mode_int=1&thrivecart_account=generic&thrivecart_secret=JLZE3Y5FGEP3&base_product=2&order_id=1514394&invoice_id=000000004&currency=USD&customer_id=6702306&customer%5Bid%5D=6702306&customer%5Bemail%5D=jsmith%40email.com&customer%5Baddress%5D%5Bcountry%5D=NZ&customer%5Baddress%5D%5Bstate%5D=Bay%20of%20Plenty&customer%5Baddress%5D%5Bline1%5D=1234%20Main%20Street&customer%5Baddress%5D%5Bcity%5D=Auckland&customer%5Baddress%5D%5Bzip%5D=3345&customer%5Bip_address%5D=255.255.255.255&customer%5Bname%5D=John%20Smith&customer%5Bcheckbox_confirmation%5D=false&customer%5Bfirst_name%5D=John&customer%5Blast_name%5D=Smith&order%5Btax%5D=null&order%5Btax_type%5D=null&order%5Bprocessor%5D=stripe&order%5Btotal%5D=10000&order%5Btotal_str%5D=100.00&subscription%5Btype%5D=product&subscription%5Bid%5D=2&subscription%5Bname%5D=Webhook%20testing&subscription%5Bprocessor%5D=stripe

Here’s an order.refund example.

event=order.refund&mode=test&mode_int=1&thrivecart_account=generic&thrivecart_secret=JLZE3Y5PRMF2&base_product=2&order_id=1514394&invoice_id=000000004&currency=USD&customer_id=6702306&customer%5Bid%5D=6702306&customer%5Bemail%5D=jsmith%40email.com&customer%5Baddress%5D%5Bcountry%5D=NZ&customer%5Baddress%5D%5Bstate%5D=Bay%20of%20Plenty&customer%5Baddress%5D%5Bline1%5D=1234%20Main%20Street&customer%5Baddress%5D%5Bcity%5D=Auckland&customer%5Baddress%5D%5Bzip%5D=3345&customer%5Bip_address%5D=255.255.255.255&customer%5Bname%5D=John%20Smith&customer%5Bcheckbox_confirmation%5D=false&customer%5Bfirst_name%5D=John&customer%5Blast_name%5D=Smith&order%5Btax%5D=null&order%5Btax_type%5D=null&order%5Bprocessor%5D=stripe&order%5Btotal%5D=10000&order%5Btotal_str%5D=100.00&refund%5Bamount%5D=10000&refund%5Bamount_str%5D=100.00&refund%5Btype%5D=product&refund%5Bid%5D=2&refund%5Bname%5D=Webhook%20testing&refund%5Bprocessor%5D=stripe