Rewarded Video Completion Webhook

This is a webhook interface, implemented by the Game SVR with the callback URL configured in the SUD OP console. The SUD OP SVR calls this interface after the APP ad platform passes completion verification, notifying the Game SVR to grant the reward.

Interface Description

Interface Name ad.rewardNotify

Description Rewarded video completion webhook. After the APP ad platform passes completion verification, the SUD OP SVR proactively calls the callback URL configured by the Game SVR, notifying the Game SVR to grant the reward.

Note: This interface requires service communication secondary encryption and signatures: the callback request must be signature-verified and decrypted before any business logic runs. This effectively prevents data tampering and leakage.

Interface Information

Item	Value
Caller	SUD OP SVR
Provider	Game SVR
Trigger timing	After the APP ad platform passes completion verification

Call Method

HTTPS Call

POST <Game custom callback URL>

The callback URL is configured by the Game in the SUD OP console. Please use an HTTPS address.

Request Parameters - Body

Field	Type	Default	Required	Description
id	string		Yes	Webhook notification ID
create_time	number		Yes	Webhook notification creation time (second-level timestamp)
event	string		Yes	Event type, fixed as ad_reward_notify
payload	object		Yes	Event data, see the description below

payload Field Description

Rewarded video completion notification: ad_reward_notify

Field	Type	Default	Required	Description
transaction_id	string		Yes	Transaction ID generated by SUD OP, used as an idempotency key to prevent duplicate reward granting
user_id	string		Yes	User identifier, passed in by the client via setServerSideVerificationData
reward_item	string		Yes	Reward item name, e.g. Coins, passed in by the client via setServerSideVerificationData
reward_amount	number		Yes	Reward amount, passed in by the client via setServerSideVerificationData
custom_data	string		No	Developer custom data, passed in by the client via setServerSideVerificationData
ad_unit_id	string		Yes	SUD OP ad unit ID

Security note: reward_item, reward_amount, and custom_data are all passed in by the client via setServerSideVerificationData and carry the risk of being tampered with. The Game SVR must determine the real reward item and amount based on server-side configuration (such as the reward spec table corresponding to ad_unit_id), and must never directly trust the reward_amount in the payload when granting rewards. The legitimacy of user_id/custom_data must likewise be verified on the server side.

Response

The returned JSON data package

Field	Type	Description
errcode	int32	Error code. 0 indicates the protocol layer processed successfully (signature verification, decryption, and field parsing all passed)
errmsg	string	Error message
is_valid	boolean	Business-layer reward granting result. true: the reward was granted; false: business validation did not pass or no reward was granted this time (e.g. missing reward configuration, illegitimate user, idempotency hit already processed, etc.)

Response Semantics Convention

Scenario	Recommended response
Signature verification / decryption failed	Reject the request directly and return a non-200 HTTP status code (such as 401 / 403). Do not enter the business layer and return is_valid: false. SUD OP will retry or alert accordingly
Protocol normal, reward granted successfully	errcode: 0 + is_valid: true
Protocol normal, idempotency hit (same transaction_id already processed)	errcode: 0 + is_valid: true (treated as already granted, but not granted again)
Protocol normal, business validation not passed (e.g. user does not exist, reward configuration missing)	errcode: 0 + is_valid: false
Game SVR internal error, expecting SUD OP to retry	Return a non-200 HTTP status code or a non-zero errcode

Example

Request Example

{
  "id": "notify_20260429_abc123",
  "create_time": 1745929600,
  "event": "ad_reward_notify",
  "payload": {
    "transaction_id": "sudtx_20260423_abc123xyz",
    "user_id": "user-001",
    "reward_item": "Coins",
    "reward_amount": 10,
    "custom_data": "level=5",
    "ad_unit_id": "sud_ad_unit_abc123"
  }
}

Response Example

Reward granted successfully:

{
  "errcode": 0,
  "errmsg": "ok",
  "is_valid": true
}

Validation failed:

{
  "errcode": 0,
  "errmsg": "ok",
  "is_valid": false
}

The example above represents that protocol-layer validation passed but the business layer did not grant a reward (e.g. user_id does not exist, ad_unit_id has no reward spec configured, etc.). For signature verification failures, reject the request directly as described in the "Response Semantics Convention" above; do not use this response.

Idempotency

• The Game SVR uses payload.transaction_id as the idempotency key to ensure that a reward is granted only once for the same completion transaction.
• When the SUD OP SVR retries sending the same transaction_id due to a timeout, the Game SVR should return is_valid: true but not grant the reward again.

Timeout and Retry

Item	Requirement
Game response timeout threshold	≤ 5 s
Conditions that trigger a retry	The Game SVR does not respond within the timeout threshold, returns a non-200 HTTP status code, or returns a non-zero errcode
Total retry count	Up to 15 times
Retry interval (seconds)	15, 15, 30, 180, 600, 1200, 1800, 1800, 1800, 3600, 10800, 10800, 10800, 21600, 21600 (approximately 24 hours in total)

Returning errcode: 0 + is_valid: false is treated as the business layer proactively refusing to grant the reward, and will not trigger a retry. If you need SUD OP to retry, return a non-zero errcode or a non-200 status code.

Authentication

When SUD OP calls this interface, it always carries encryption and signature information in the request; there is no plaintext webhook mode. The Game SVR must verify the signature and decrypt the request to confirm the request source is legitimate before granting any reward.

Notes

1. transaction_id must be checked for idempotency to prevent duplicate reward granting when the SUD OP SVR retries.
2. The Game SVR must verify the signature. If verification fails, reject the request directly (return a non-200 HTTP status code); do not enter the business response flow, to avoid forged requests triggering reward granting.
3. Client pass-through fields such as reward_item / reward_amount are untrusted. Before granting a reward, the real reward spec must be verified on the server side based on server-side configuration such as ad_unit_id.
4. Requests whose create_time differs from the server's current time by more than 5 minutes should be rejected directly to prevent replay attacks.
5. The SUD OP SVR only calls this interface after APP completion verification passes; the Game SVR does not need to re-verify with the APP platform.