Custom Webhooks Reference
Article:
If you code your own webhooks, you may find this guide to custom webhook field descriptions handy.
Supported Webhooks
- Sale - sent after a regular or a recurring product has been purchased;
- Rebill - sent after a recurring product's next payment date has passed. The Rebill webhook is fired even if no charge happens (for example, for a product with 2 free trial periods);
- Rebill Cancellation - sent after recurring payments on an order have been cancelled. The Rebill Cancellation webhook is fired only if the order has any recurrent payments left;
- Refund - sent after a payment has been refunded. The Refund webhook is not fired for products that haven't been paid for (for example, recurring products with a free trial period while the trial period is in effect).
- Lead Capture - sent after form submission. The lead capture webhooks aren’t fired unless you configure the webhook URL on the page.
- Tracking data - UTM tag data, FB Click ID and Google Click ID are sent with the webhook payload.
Webhook Payload
All of the following fields are present in every webhook message, but some may be empty:
|
Field Name
|
Description
|
Format
|
|---|---|---|
| ccurrency | Currency of charge | 3 uppercase letters, ISO 4217 ( https://en.wikipedia.org/wiki/ISO_4217) |
| ccustcc | Customer country | Alphanumeric, no specific format |
| ccustemail | Customer email | |
| ccustname | Customer name | Alphanumeric, no specific format |
| ccuststate | Customer state | Alphanumeric, no specific format |
| cproditem | Convertri product ID | UUID |
| ccusttitle | Customer title | Alphanumeric, no specific format |
| ccustfirstName | Customer first name |
Alphanumeric, no specific format |
| ccustlastName | Customer last name |
Alphanumeric, no specific format |
| ccustmiddleNames | Customer middle names |
Alphanumeric, no specific format |
| ccustphone | Customer phone |
Numeric |
| ccustaddress | Customer address |
Alphanumeric, no specific format |
| ccustaddress2 | Customer address2 |
Alphanumeric, no specific format |
| ccustcity | Customer city |
Alphanumeric, no specific format |
| ccustzipCode | Customer zipCode |
|
| ccustshippingAddress | Customer shipping address |
Alphanumeric, no specific format |
| ccustshippingAddress2 | Customer shipping address2 |
Alphanumeric, no specific format |
| cshippingamount | Amount charged for shipping a product in pennies ($10.00 = 1000). Please note that this may be zero in case of free shipping. |
Numeric |
| ccustshippingCity | Customer shipping city |
Alphanumeric, no specific format |
| ccustshippingState | Customer shipping state |
Alphanumeric, no specific format |
| ccustshippingCountry | Customer shipping country |
Alphanumeric, no specific format |
| ccustshippingZipCode | Customer shipping zip code |
|
| ccustwebsite | Customer website |
Alphanumeric, no specific format |
| ccustnotes | Customer notes |
Alphanumeric, no specific format |
| cprodtitle | Product name |
Alphanumeric, no specific format |
| corderid | Order ID in Convertri |
UUID |
| cordermode | Checkout mode used for making order |
Literal value: live - when Live mode is selected, live keys for Stripe or Paypal are used test - when Test mode is selected, test keys for Stripe or Paypal Sandbox are used |
| cquantity | number |
Numeric |
| cprodtype | Product type (recurring or not) | Literal value:
|
| ctaxamount | Amount charged for tax for a product purchase in pennies ($10.00 = 1000).Please note that this may be zero in case of a free trial. |
Numeric |
| ctransaction | Transaction type | Literal value:
|
| ctransamount | Amount charged for a product in pennies ($10.00 = 1000).Please note that this may be zero in case of a free trial. |
Numeric |
| ctranspaymentmethod | Payment method selected by the customer | Literal value:
|
| ctransreceipt | Convertri order product ID | UUID |
| ctranstime | Unix timestamp transaction occured at (in seconds) | Timestamp |
| cverify | Transaction verification signature | Alphanumeric, 8 characters |
| ip | IP address of a customer at the moment of checkout | |
| fbp | Facebook pixel ID | parameter value must be of the form version.subdomainIndex. creationTime.randomnumber See https://developers.facebook.com/docs/ marketing-api/conversions-api/ parameters/fbp-and-fbc/ for details. |
| fbclid | Facebook click ID | parameter value must be of the form version.subdomainIndex.creationTime.fbclid See https://developers.facebook.com/docs/ marketing-api/conversions-api/ parameters/fbp-and-fbc/ for details. |
| gclid | Google click ID | See https://support.google.com/ google-ads/answer/9744275?hl=en |
| utm_campaign | Convertri Analytics utm_campaign | utm_campaign value |
| utm_source | Convertri Analytics utm_source | utm_source value |
| utm_medium | Convertri Analytics utm_medium | utm_medium value |
| utm_content | Convertri Analytics utm_content | utm_content value |
| utm_term | Convertri Analytics utm_term | utm_term value |
| cprodvar1 | First variant category as set up in the product *** | Alphanumeric, no specific format |
| cprodvar2 | Second variant category as set up in the product *** | Alphanumeric, no specific format |
| cprodvar3 | Third variant category as set up in the product *** | Alphanumeric, no specific format |
NOTE: Convertri takes the values of the tracking fields from the query string on checkout or opt-in page.
*** When sending variant data for a product it follows the product webhook standard for sending fields if they are empty.
Verifying Webhooks Received From Convertri
The 'cverify' field is generated from a combination of your webhook secret key, the webhook payload and a crytographic function. It allows you to check that:
- The webhook genuinely came from Convertri.
- None of the information in the payload has been tampered with.
To verify the webhook you've received, you'll need to generate your own 8-character verification code and compare it with the 'cverify' included in the webhook payload.
To create the verification code:
- Remove the 'cverify' key and its value from the request payload.
- Alphabetically sort the remaining payload by key name.
- Combine the values of the remaining payload into one long string with a pipe "|" character between each value (e.g. yours will be a lot longer, but something like "USD|name@example.com|1d5132c2-18d2-4b24-9d1b-83c21fd49789").
- At the end of the long string, append another pipe "|" followed by your secret key.
- Ensure that the string is UTF-8 encoded.
- Hash the string using SHA-1.
- Change the first 8 characters of the resulting hash to uppercase.
Those first 8 uppercase characters should now match the 'cverify' that was included in the webhook payload.