S2S Reward Callback API

Overview

DARO sends an HTTP/HTTPS GET request to your server when users complete rewarded video ads. Callbacks send immediately after completion but may delay up to several minutes depending on network conditions. Use the timestamp parameter to verify time difference between impression and callback. Retry Logic: DARO retries up to 2 times if your server doesn’t respond within 5 seconds.

Setup: Configure ‘Callback URL’ for your rewarded video ad unit on the Ad Units page.

Callback URL Example

https://yourrewardedserver.com/rewards

Callback URL Request Example

https://yourrewardedserver.com/rewards?ad_unit_id=fa1c6d2f-5016-467d-b54c-672299c7db4c&custom_data=yourcustomdata&key=b46635e51e76778ec15856720114c4edd6b6c3c7aeeb2a1b51dc346640cbca45&timestamp=1546300800&transaction_id=32ffe34770064d5c41c24deb3afd6a9fe072d2f423471851c869da6a9bc09ce3&user_id=youruserid

Query Parameters

Parameters included as query strings in callback URL. Optional parameters (custom_data and user_id) pass as null if not set.

Query Parameter	Description	Example	Data Type
ad_unit_id	Ad unit ID (UUID v4)	fa1c6d2f-5016-467d-b54c-672299c7db4c	String
custom_data (optional)	Custom data (URL encoded). Recommended to keep string size under 8192 characters.	my%20custom%20data	String
key	Verification key generated through the following process: 1. Initialize HMAC SHA256 with ‘Callback Verification Key’* 2. Generate digest with transaction_id 3. Hex encode	b46635e51e76778ec15856720114c4edd6b6c3c7aeeb2a1b51dc346640cbca45	String
timestamp	Timestamp when ad impression was recorded(integer, Epoch Time)	1546300800	Int
transaction_id	Unique transaction ID, 32-character hex	0d0f748fcd0d4a4a9f6ac809216564b1	String
user_id (optional)	Publisher-defined user ID (URL encoded); maximum length 8192 characters	7634657898	String

Find your callback verification key at https://dashboard.daro.so/service/account

Response Status Codes and Retries

DARO uses the HTTP response status code to determine whether callback delivery is complete. A 408, 429, or 5xx response, or a network error, triggers automatic retries. If those attempts continue to fail, the callback may be sent again later.

Do not return 500 for a business rejection that your server has finished processing.If your server received the callback and completed its reward decision, respond with 200 or 204 even when no reward is granted. A 500 is treated as a temporary server failure, causing unnecessary automatic retries and potentially another delivery later.

Server processing result	Recommended response	Why
Callback received and decision completed (reward granted or declined by a business rule)	`200 OK` or `204 No Content`	Processing is complete and no further delivery is needed. Do not use `500` for a business decline.
A previously processed `transaction_id` is received again	`200 OK` or `204 No Content`	Reuse the stored result without granting the reward twice. Returning `409` or `500` for a duplicate callback is not recommended.
The same request can never be processed because its format, authentication, or input is invalid	An appropriate `4xx` such as `400`, `401`, or `403`	The request must be corrected. This excludes retryable `408` and `429` responses.
A timeout, rate limit, or temporary server failure requires DARO to try again	`408`, `429`, or `5xx`	These statuses indicate a temporary failure for which callback redelivery is needed.

The response body can follow your own requirements. DARO determines whether to retry from the HTTP status code, not the response body.

Handle Duplicate Callbacks

The same callback may be delivered more than once because of network conditions or retries. Process callbacks idempotently using transaction_id: store the processing result, and if the same transaction_id arrives again, do not grant the reward twice and respond with 2xx based on the stored result.

Set Publisher-Defined User ID and Custom Data

Set user_id and custom_data on the client side using platform-specific SDK methods. These optional values send with the callback. Platform Guides:

Getting Started

SDK Integration

How to Use DARO

FAQ

S2S Reward Callback API

Overview

Callback URL Example

Callback URL Request Example

Query Parameters

Response Status Codes and Retries

Handle Duplicate Callbacks

Set Publisher-Defined User ID and Custom Data

​Overview

​Callback URL Example

​Callback URL Request Example

​Query Parameters

​Response Status Codes and Retries

​Handle Duplicate Callbacks

​Set Publisher-Defined User ID and Custom Data

Overview

Callback URL Example

Callback URL Request Example

Query Parameters

Response Status Codes and Retries

Handle Duplicate Callbacks

Set Publisher-Defined User ID and Custom Data