Using webhook notifications

ThriveCart supports the delivery of webhook notifications on certain 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 act on this POST and run actions such as integrations with third-party platforms, send yourself or the customer further emails, etc.

Your script must also respond with an HTTP 2xx status code when we send a HEAD request to it, otherwise, we will not allow you to add it.

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.

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 started to be sent there as they trigger in ThriveCart.

3. 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 www.webhook.site. This service will provide you with a URL you can add into ThriveCart. It will then log all transactions processed and break down the data so you can easily review it.

3. Verifying the webhook

As part of the parameters that we provide, we include a thrivecart_secret parameter. This is a string which will match up with the ‘Secret word’ that can be found under your Settings > API & Webhooks > ThriveCart API 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

We include the following parameters in our notifications. 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 which 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)

Webhook events

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

  • order.success
  • order.subscription_payment
  • order.subscription_cancelled
  • order.refund
  • 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 at 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 requests 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 it’s 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.

Further, more detailed API documentation is coming in the future.

Let’s look at some examples

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

 

Related Articles