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

Setting up a webhook

Your webhook must be accessible via the internet, and must return an 2xx HTTP status code when we ping it with either a HEAD or a POST request. You can create up to 5 webhooks in total; if you require more, you can get in touch with us and request raising this limit. Sign in to your ThriveCart account, click on Settings at the top, navigate down to Webhooks and provide the name of the hook (for your reference in future) 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.

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 Settings -> ThriveCart API. 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.

Parameters

We include the following parameters in our notifications. Note that any and all keys representing prices are in hundreds. 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.

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)

Other events

As well as the ‘order.success’ event, we also provide the following:

  • order.subscription_payment
  • order.refund
  • order.subscription_cancelled
  • affiliate.commission_earned
  • affiliate.commission_payout
  • affiliate.commission_refund

Debugging a 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 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 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 the 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 soon.

Related Articles