[POST] Send webhooks
Request description
The webhooks are sent when triggered by the events available for a product in an order.
NOTE: If there are several products in one order, you receive an individual webhook for each of the products.
Request contains:
(Optional) Installment data
(Optional) Subscription data
(Optional) Order additional parameters
(Optional) Refund data
Request Specification:
Request Method: POST
Data Transfer Format: JSON
Encoding: UTF-8
Header Parameters
content-type
string
required
MIME-type
It must be equal to "application/json".
signature
string
required
Webhook signature
Webhook signature verification allows you to rest assured that the webhooks received are from Noventiq.
Format: hash, generated with algorithm SHA-512, from string:
[secret key];[event];[order_id];[create_date];[payment_method];[currency];[customer.email]where:
secret key - when setting up webhooks
event; order_id; create_date; payment_method; currency; customer.email - the values coincide with the values of the corresponding webhook fields
See the signature generation example.
Body Parameters
event
string
required
Notification-triggering event
For the value options, see the reference guide.
event_date
string
required
Date and time of event
The system send a webhook on this event.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
order_id
number
required
Order identifiers
order_name
string
required
Extended order identifier
In such a format prefixes can be added to identifiers. This is the way order numbers are viewed by customers.
status
string
required
Order status.
Value options:
not paid
paid
deleted
The status is also used if a full refund has been made.
More details on order statuses.
external_id
string
Checkout page identifier
It is used if an order for a product with dynamic characteristics has been placed. You receive this identifier in response to the request used for generating a buy link to purchase a product with dynamic characteristics (buy_link).
Otherwise, the parameter is transferred having an empty value ("").
create_date
string
required
Date and time of creation for order
If a webhook is sent on the order.created event, the date and time values in this parameter will be equal to the values transferred in event_date.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
pay_date
string
Date and time of successful order payment completion
If a webhook is sent on the order.payment.succeeded event, the date and time values in this parameter will be equal to the values transferred in event_date.
Format: YYYY-MM-DDThh:mm:ss±hh:mm
If no payment has been made, the parameter is transferred having an empty value ("")
currency
string
required
Currency code of order
Format: ISO 4217 alpha-3, 3 characters
For the value options, see the reference guide
locale
string
required
Checkout page interface language
For the value options, see the reference guide.
order_detail_url
string
required
Link leading to the order page
When receiving webhooks in the test environment - links will be intended for the test environment (links will have the .demoslweb.com suffix added).
customer
object
required
Customer data
customer / country
string
required
Customer's country code
Format: ISO 3166-1 alpha-2
For the value options, see the reference guide
customer / type
string
required
Customer type
Value options:
physical - individuals
juridical - companies
customer / email
string
required
Customer's email
customer / first_name
string
required
Customer's name
customer / last_name
string
required
Customer's last name
customer / phone
string
Customer's phone number
If the parameter contains no value on our end, it is transferred empty ("").
customer / vat_number
string
Taxpayer identification number
E.g., it is used to transfer:
DNI/CUIL/CUIT when payments are made in Argentine pesos.
If the parameter contains no value on our end, it is transferred empty ("").
customer / company_name
string
Company name
If the parameter contains no value on our end, it is transferred empty ("").
customer / company_billing_address
string
Company's registered office address
If the parameter contains no value on our end, it is transferred empty ("").
customer / company_delivery_address
string
Company’s physical address
If the parameter contains no value on our end, it is transferred empty ("").
product
object
required
Order product data
product / id
string
required
Product identifiers
product / vendor_code
string
Your product identifiers
If the parameter contains no value on our end, it is transferred empty ("").
product / sku
string
Your product SKU
If the parameter contains no value on our end, it is transferred empty ("").
product / business_segment
string
Product sales business segment
Value options:
b2c - product is intended for individuals
b2b - product is intended for legal entities
mobile - mobile app
If the parameter contains no value on our end, it is transferred empty ("").
product / name
string
required
Full names of products
product / price
string
required
Price per product unit
It is transferred in order currency
Price excluding discount and excluding VAT
Format: String contains numerals; value separating by point, with two decimal places.
product / quantity
number
required
Product unit quantities
product / discount_percent
string
Product discount percentage
It is transferred if a discount is applied to a product in an order at checkout. Otherwise, the parameter is transferred having an empty value ("").
product / discount_amount
string
Product discount amount
It is transferred if a discount is applied to a product in an order at checkout. Otherwise, the parameter is transferred having an empty value ("").
It is transferred in order currency
Format: String contains numerals; value separating by point, with two decimal places
product / vat_percent
string
required
VAT percentage
product / vat_amount
string
required
VAT amount
Product quantity in an order and a discount are taken into account.
It is transferred in order currency
Format: String contains numerals; value separating by point, with two decimal places
product / amount
string
required
Product total price
It is transferred in order currency
Price including product quantities, VAT and discounts
Format: String contains numerals; value separating by point, with two decimal places
product / margin
string
required
Your profit margin from sales
It is transferred in order currency
Format: String contains numerals; value separating by point, with two decimal places
product / activation_codes
array [strings]
Product license information sent to customers.
The parameter is transferred if a product exploits the Noventiq automatic fulfillment tools (electronic delivery option) to send its license information, or the license information of the product has already been sent and the data has been saved in Noventiq.
payment
object
required
Payment data
payment / payment_method
string
required
Payment method code
For the value options, see the reference guide.
payment / payment_system_name
string
required
Payment method name
This name is seen by customers on the checkout page when they place an order.
payment / payment_error_code
string
required*
Payment error code
* - Required, if an error occurs during payment.
payment / payment_error_description
string
required*
Payment error description
* - Required, if an error occurs during payment.
payment / card_type
string
Сard type
Example: Visa, MASTERCARD.
The value can be transferred if:
The customer has paid for their order with a card
The order was created to renew an AR subscription (child) but the customer has not paid for it yet. In this case, the parameter value is taken from the parent order if it was paid with a card
Otherwise, the parameter is transferred with an empty value ("").
payment / card_last_4
string
Last 4 digits of card number
The value can be transferred if:
The customer has paid for their order with a card
The order was created to renew an AR subscription (child) but the customer has not paid for it yet. In this case, the parameter value is taken from the parent order if it was paid with a card
Otherwise, the parameter is transferred with an empty value (null).
payment / card_expiration_date
string
Card expiration date
The value can be transferred if:
The customer has paid for their order with a card
The order was created to renew an AR subscription (child) but the customer has not paid for it yet. In this case, the parameter value is taken from the parent order if it was paid with a card
Format: MM/YYYY. Example: 12/2026
Otherwise, the parameter is transferred with an empty value ("").
payment / is_card_expired
boolean
Attribute indicating whether card expires before subscription expiration date.
The value can be transferred if:
The order contains a subscription (AR or PMR).
A card is used for payment and its expiration date is set (the payment.card_expiration_date parameter was transferred). If the order was created to renew a subscription (child order) and the customer has not paid for it yet, the parameter value is taken from the parent order.
The current subscription status does not affect the parameter.
Value options:
true - bank card expires before subscription does (payment.card_expiration_date < subscription.expiration_date).
For example:Card expiration date (payment.card_expiration_date) = 09.2026 (i.e. card is valid until 30.09.2026)
Subscription expiration date (subscription.expiration_date) = 15.10.2026
Since Card expiration date < Subscription expiration date, then subscription.is_card_expired transfers true
false - bank card expires after subscription does (payment.card_expiration_date ≥ subscription.expiration_date)
For example:Card expiration date (payment.card_expiration_date) = 10.2026 (i.e. card is valid until 31.10.2026)
Subscription expiration date (subscription.expiration_date) = 15.10.2026
Since Card expiration date > Subscription expiration date, then subscription.is_card_expired transfers false
payment / is_installment_payment
boolean
required
Installment payment availability
More details on payment in installments. This parameter and all the other ones concerning installment payment include only the installments of Noventiq Checkout (installments of PSP are not included).
Value options:
true - no installments (one-time payment)
false - installments
payment / installment_amount
string
required*
One installment amount
* - Required, if payment.is_installment_payment is true, otherwise, it is not transferred
Format: Numeral with 2 decimal places, separator - point. Transferred as a string
The amount of the last installment may slightly differ from the remaining installment amounts
payment / installment_currency
string
required*
Currency code of one installment payment amount
* - Required, if payment.is_installment_payment is true, otherwise, it is not transferred
Always equals the value of the currency parameter
payment / installment_choice
number
required
Number of installments
* - Required, if payment.is_installment_payment is true, otherwise, it is not transferred.
subscription
object
Subscription data
It is transferred if an auto-renewable subscription (AR / AR Trial) or a pre-filled manual renewal (PMR) is issued for a product.
Note: A subscription is created after the initiating order has been paid for. Therefore, for such an order parameter subscription is generally not transferred in event order.created since no subscription has been created yet. Parameter subscription is transferred for event order.created in two cases:
An order has been created to renew a subscription (child order)
An order initiates a subscription (parent order) and payment has already been completed successfully by the time the order creation notification is sent, i.e. the subscription has already been created.
subscription / id
string
required*
Subscription identifier
* - Required, if the subscription parameter is transferred
Format: NN_MM, where NN is an identifier of the order that initiates subscriptions (parent order)
subscription / previous_order_id
number
required*
ID of previous order within subscription
If a current order is a parent one and initiates a subscription, the parameter is transferred having value "null"
If a current order is a child one, this parameter transfers the identifier of a previous child order (or the identifier of a parent order in case it is the first renewal)
* - Required, if the subscription parameter was transferred.
Example:
If a subscription included orders 0001 (subscription initiator), 0002 (1st subscription renewal), 0003 (2nd subscription renewal), and a webhook is sent upon the event that has happened to:
Order 0001, then "order_id":0001, "subscription.previous_order_id":null
Order 0002, then "order_id":0002, "subscription.previous_order_id":0001
Order 0003, then "order_id":0003, "subscription.previous_order_id":0002
Note, the webhook on cancellation/resumption of the subscription is always sent for the parent order ("order_id":0001), so it will always transfer the following: "subscription.previous_order_id":null (regardless of any child orders existing at the time of the event happening to the subscription).
subscription / previous_order_item_id
number
required*
Order item ID of previous order within subscription
Order item ID is an additional internal ID that is assigned to a product within an order.
If the current order is a parent order (initiates the subscription), the parameter is transferred having an empty value (null)
If the current order is a child order, the parameter transfers the order item ID assigned to the product of the previous order created within the subscription
* - Required, if the subscription parameter was transferred.
Example:
A product being from a parent order triggers creation of a subscription. This product ID is 11111:
Order item ID 12345 gets assigned to the product within the order
The webhook sent on the order event contains the following: "subscription.previous_order_item_id":null
During the first subscription renewal, a renewal order is created:
Product having ID 22222 is used to renew the subscription
Order item ID 54321 gets assigned to the product within this
The webhook sent on the order event contains the following: "subscription.previous_order_item_id":12345
Note, webhooks on cancellation/resumption of the subscription are always sent for the parent order, so they always transfer the following: "subscription.previous_order_item_id":null (regardless of any child orders existing at the time of the event happening to the subscription).
subscription / type
string
required*
Subscription type
* - Required, if the subscription parameter is transferred.
Value options:
AR - auto-renewable subscription (including AR Trial)
PMR - pre-filled manual renewal
More details оn subscription types.
subscription / is_conversion_from_trial
boolean
required*
Attribute indicating first renewal after free trial period
It indicates whether the order on which you received a webhook had been created or not to renew a subscription immediately after its free trial period expiration.
* - Required, if the subscription parameter is transferred.
Value options:
true - if all the conditions are met:
The order renews an AR subscription. (The order is a child order. The subscription.type parameter equals AR)
This is the first child order of this subscription
The subscription has a free trial period. (The customer purchased the parent product free of charge)
false - if the conditions for transferring true are not met
subscription / status
string
required*
Subscription status
* - Required, if the subscription parameter is transferred.
Value options:
active - subscription is in progress and requires no payment
not paid - subscription is payment pending
cancelled - renewal is cancelled
More details on the statuses of auto-renewable subscriptions (AR). Pre-filled manual renewal (PMR) subscriptions exploit the same statuses, however, the following options are not available: subscription cancellation or subscription restoration.
subscription / period
string
required*
Product term within current subscription period
This is the validity period of the product from the last paid order created as part of the subscription. Please note that this period applies to the subscription as the whole and may not coincide with the term of the product in the order for which the webhook is sent.
Example:
A subscription for the product having a 7-day term has been created:
subscription.period = P7D is transferred in the webhook.
A child order for the product having a 1-month term has been created:
subscription.period = P7D is transferred in the webhook on the event; since the child order has not yet been paid for and the subscription has not yet been renewed, the term from the current subscription period is transferred.
A payment for the child order has been made:
subscription.period = P1M is transferred in the webhook on the event; since the child order has been paid for, the subscription has been extended and the current subscription period has been updated.
Format:
* - Required, if the subscription parameter is transferred
ISO 8601 code: P[number][unit of measurement]
Supported units: Y - year, M - month, D - day
Example: "P1Y" matches "1 year"
subscription / expiration_date
string
required*
Subscription expiration date
* - Required, if the subscription parameter is transferred
Format: YYYY-MM-DDThh:mm:ss±hh:mm
subscription / next_charge_date
string
required*
Date of next attempt to pay for AR subscription
Only the date of the first payment attempt is transferred. The system ignores additional attempts in case of unsuccessful payment. If the date comes but the attempt is unsuccessful, or the system runs out of all the attempts to pay for a subscription (the subscription has not been renewed), the data transferred does not change. The system calculates a new date to pay for the next renewal after successful payment.
* - Required, if the subscription parameter was transferred and the subscription.type parameter equals AR
Format: YYYY-MM-DDThh:mm:ss±hh:mm
subscription / detail_url
string
required*
Link to manage auto-renewable subscriptions (AR, AR Trial)
This anchor link leads to the subscription section within the subscription order initiator page.
- Required, if the subscription parameter is transferred, and the subscription.type parameter is equal to AR. Otherwise, the parameter is not transferred.
Note:
If a webhook notifies of a subscription order initiator (parent), the order_detail_url parameter and the subscription.detail_url parameter contain a link to the same page
If a webhook notifies of a renewal order (child), these parameters have different values: order_detail_url - leads to the renewal order page, а subscription.detail_url – leads to the subscription order initiator page
When receiving webhooks in the test environment - links will be intended for the test environment (links will have the .demoslweb.com suffix added)
additional_data
array [objects]
Additional parameters of order
More details on additional parameters. Please note that the time for storing additional parameters in orders is limited.
additional_data / [object] / name
string
required*
Parameter name
* - Required, if the additional_data parameter is transferred.
additional_data / [object] / value
string
required*
Parameter value
* - Required, if the additional_data parameter is transferred.
return
object
Refund / return data
It is transferred if a webhook is sent on the product.returned event. Otherwise, it is not transferred.
return / type
string
required*
Action type
* - Required, if the return parameter is transferred.
Value options:
returned - refund or replacement of license information
removed - removal of incorrect license information, e.g., when the customer receives invalid data instead of license information because of technical issues
return / date
required*
Date and time of event
If a webhook is sent on the product.returned event, the date and time values in this parameter will be equal to the values transferred in event_date.
* - Required, if the return parameter is transferred
Format: YYYY-MM-DDThh:mm:ss±hh:mm
return / reason
string
required*
Reason description for event
* - Required, if the return parameter is transferred.
document_part
string
required
Order item sequential number
Sequential numbering of items remains for all events.
Format: "[item sequential number in order]-of-[total amount of items in order]".
E.g.: "1-of-2", if there are only two products in an order and a notification is sent for the first product.
Response
If a webhook is successfully received, your web service should return a response to the received webhook. Response time: 1 minute.
Possible responses:
HTTP/1.1 200 OK - webhook successfully received
Any other response or no response - webhook not received
If no webhook has been received, then:
Sending is repeated according to the following schedule: once every 20 minutes
Retries continue until the HTTP/1.1 200 OK response code is received or 10 attempts are made
When re-sending, webhook data is not updated. If an order/payment object changes when a webhook is being sent, the contents of the webhook are not changed
Noventiq Checkout
Support | |
Our resources |