Webhook Notifications

CS2DT sends webhook notifications to your server when the status of a purchase order changes. These notifications allow your system to update the order without repeatedly querying the order-details endpoint.

Update Notes

2024-08-03 Сlarified the frequently asked questions.
2024-06-06 Initial release.

Prerequisites

Before receiving webhook notifications, complete the following configuration:

Add your webhook URL under Merchant Center → API Management.

Obtain your app_secret from Merchant Center → API Management. It is used to verify the signature of each notification.

If your server only accepts requests from approved IP addresses, add the CS2DT webhook service IP address to your allowlist: 106.15.203.246

Keep your app_secret secure. Do not expose it in client-side code, public repositories, logs, or screenshots.

Notification Mechanism

When the status of a purchase order changes, CS2DT sends an HTTP POST request to your configured webhook URL. The request body contains JSON data.

After successfully processing the notification, return success in the response body. Otherwise, CS2DT will treat the notification as unsuccessful and retry it.

If your server does not return success, CS2DT treats the notification as unsuccessful and retries it according to the retry policy. The interval between retries increases exponentially, with a maximum of 16 retries.

Because notifications may be delivered more than once, your webhook handler should process duplicate notifications safely.

Signature Verification

Every webhook notification includes a sign field. Use it to verify that the notification was sent by CS2DT and that its contents have not been modified.

To verify the signature:

Remove the sign field from the notification parameters.

Treat every null value as the literal string null.

Perform url_decode on the remaining parameters.

Sort the parameters by name in ascending ASCII order.

Join the parameters in the following format, using & between each pair:

key1=value1&key2=value2&key3=value3

Append your app_secret in the following format:

&sign={app_secret}

For how to get it, please refer to the Prerequisites section

Generate an MD5 hash from the complete string and convert the result to 32 uppercase characters.

Compare the generated hash with the sign value included in the notification.

The signature is valid if both values match.

Order message notification

Return result example

The following is an example of the string used to generate the signature:

offerId=null&orderId=753955645187293184&outTradeNo=753955643962990592&status=11&statusName=failed&tradeOfferId=null&type=0&typeName=BUYER_ORDER_STATUS&sign={your_app_secret}

Replace {your_app_secret} with your actual app_secret before generating the MD5 hash.

Notification Fields


Field	Description
`orderId`	The CS2DT order ID returned by the purchase endpoint.
`sign`	The signature used to verify that the notification was sent by CS2DT. Signature verification is strongly recommended.
`status`	The current numeric status of the purchase order.
`statusName`	The text identifier corresponding to status.
`tradeOfferId`	The Steam trade-offer ID. This field is returned only when status is 3.
`offerId`	The CS2DT trade-offer ID. This field is returned only when status is 3.
`outTradeNo`	The merchant order number provided when submitting a v2 purchase request. CS2DT returns the same value in webhook notifications.
`type`	The notification type. A value of 0 identifies a purchase-order notification.
`typeName`	The notification-type identifier. BUYER_ORDER_STATUS identifies a purchase-order status notification.

Order Statuses


status	statusName	Description
1	waiting_delivery	The purchase order was created successfully and is awaiting delivery from the seller.
3	waiting_receive	The Steam trade offer is ready. Notify the buyer that they need to accept it.
10	success	The buyer accepted the Steam trade offer. Order settlement is in progress.
11	failed	The order was cancelled or failed.
200	settled	Settlement is complete. This is a final status.
220	recalled	The order was reversed. This is a final status.

Opening the Steam Trade Offer

When status is 3, use tradeOfferId to create the Steam trade-offer URL:

The notification may also include offerId, which identifies the trade offer in CS2DT. You can use offerId to retrieve additional information.

Update Notes#

Prerequisites#

Notification Mechanism#

Signature Verification#

Order message notification#

Notification Fields#

Order Statuses#

Opening the Steam Trade Offer#