Interaction Specification When Receiving Webhooks

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:

Request Specification:

  • Request Method: POST
  • Data Transfer Format: JSON
  • Encoding: UTF-8
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 Softline.
Format: hash, generated with algorithm SHA-512, from string:
[secret key];[event];[order_id];[create_date];[payment_method];[currency];[customer.email]
where: See the signature generation example.
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
(For orders in Softline Checkout) Order identifiers.

(For payments in Softline Payments) Payment identifiers.
order_name
string
required
Extended order/payment identifier.
In such a format prefixes can be added to identifiers.

(For orders in Softline Checkout) This is the way order numbers are viewed by customers.
status
string
required
Order/payment status.
Value options:
  • not paid
  • paid
    (For payments in Softline Payments) The status is also used if the card verification process initiated by the /v1/payment/card/verification request has been successfully completed.
  • deleted
    The status is also used if a full refund has been made.
More details on order statuses.
external_id
string
(For orders in Softline Checkout) 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 ("").

(For payments in Softline Payments) Payment identifiers on your end.
This identifier is filled with a value from the payment_id parameter when creating a payment object or processing an auto-payment.
create_date
string
required
Date and time of creation for order/payment object.
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/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/payment.
  • 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
(For orders in Softline Checkout) 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).

(For payments in Softline Payments) Link leading to the payment form page.
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 - natural person.
  • juridical - legal person.
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
(For orders in Softline Checkout) Order product data.

(For payments in Softline Payments) Payment data.
product
/
id
string
required
(For orders in Softline Checkout) Product identifiers.

(For payments in Softline Payments) Technical values.
product
/
vendor_code
string
(For orders in Softline Checkout) Your product identifiers.
If the parameter contains no value on our end, it is transferred empty ("").

(For payments in Softline Payments) Technical values.
product
/
sku
string
(For orders in Softline Checkout) Your product SKU.
If the parameter contains no value on our end, it is transferred empty ("").

(For payments in Softline Payments) Technical values.
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
(For orders in Softline Checkout) Full names of products.

(For payments in Softline Payments) Payment descriptions. This description is filled with values of the payment_description parameter when creating a payment object or processing an auto-payment.
product
/
price
string
required
(For orders in Softline Checkout) Price per product unit in order currency.
Format: String contains numerals; value separating by point, with two decimal places.

(For payments in Softline Payments) Payment amount excluding VAT.
product
/
quantity
number
required
(For orders in Softline Checkout) Product unit quantities.

(For payments in Softline Payments) "1" is always transferred.
product
/
discount_percent
string
(For orders in Softline Checkout) 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 ("").

(For payments in Softline Payments) It is not applicable.
product
/
discount_amount
string
(For orders in Softline Checkout) Product discount amount in order currency.
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 ("").
Format: String contains numerals; value separating by point, with two decimal places.

(For payments in Softline Payments) It is not applicable.
product
/
vat_percent
string
required
VAT percentage.
product
/
vat_amount
string
required
VAT amount in order currency.
(For orders in Softline Checkout) Product quantity in an order and a discount are taken into account.
Format: String contains numerals; value separating by point, with two decimal places.
product
/
amount
string
required
(For orders in Softline Checkout) Product total price in order currency.
  • Price due to product quantities, VAT and discounts.
  • Format: String contains numerals; value separating by point, with two decimal places.
(For payments in Softline Payments) Payment total amount with VAT included.
product
/
margin
string
required
You profit margin from sales in order currency.
Format: String contains numerals; value separating by point, with two decimal places.
product
/
activation_codes
array [strings]
(For orders in Softline Checkout) Product license information sent to customers.
The parameter is transferred if a product exploits the Softline 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 Softline.

(For payments in Softline Payments) It is not applicable.
payment
/
payment
object
required
Payment data.
payment
/
payment_method
string
required
Payment method code for order/payment.
For the value options, see the reference guide.
payment
/
payment_system_name
string
required
Payment method name of order/payment object.
(For orders in Softline Checkout) 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_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 - card expires before subscription expires.
  • false - card expires after subscription has expired, т.е. [card expiration date] ≥ [subscription expiration date].
payment
/
card_last_4
number
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
/
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 Softline 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.
payment
/
installment_choice
number
required
Number of installments
* - Required, if payment.is_installment_payment is true, otherwise, it is not transferred.
subscription
object
(For orders in Softline Checkout) 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. Subscription creation happens upon successful order-initiator payment. Therefore, the subscription parameter is generally absent in the order.created event for such an order, since no subscription has been created by the time the order is created. There are two cases when the parameter may be present in the order.created event:
  • The system sends the webhook notifying of the order created to renew the subscription.
  • The system sends the webhook notifying of the order that is a subscription order initiator; and by the time the event is sent, the payment has been successfully completed, i.e. a subscription has been created.
(For payments in Softline Payments) It is not applicable.
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
/
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 validity period.
  • * - Required, if the subscription parameter is transferred.
  • Format: 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.
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]
(For orders in Softline Checkout) Additional parameters of order. More details on additional parameters. Please note that the time for storing additional parameters in orders is limited.

(For payments in Softline Payments) Values of the additional_data parameter in the payment creation request.
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.

Value options:
  • "Проблема установки / активации" - installation / activation problem.
  • "Географически ограничения" - geo-restriction.
  • "Ошибка при выборе продукта" - product selection error.
  • "Не устроил срок доставки" - unacceptable delivery period.
  • "Не возможно поставить продукт" - product delivery is impossible.
  • "Автопродление" - auto-renewal.
  • "Повторная оплата" - duplicated payment.
  • "ChargeBack".
  • "Недоволен программой" - unsatisfied with the program.
  • "TYPO".
  • "Дубли заказа" - duplicated order.
  • "Тестовый заказ" - test order.
or any other issue.
document_part
string
required
(For orders in Softline Checkout) 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.

(For payments in Softline Payments) "1-of-1" is always transferred.

Your web service should return a response to webhooks received.

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.