# Setup Postback

## Postback URL Structure

{% code overflow="wrap" %}

```html
//Example Postback URL

https://www.example.com/postbacks/postback_file_name.php?user_id={user_id}&offer_id={offer_id}&offer_name={offer_name}&payout={payout}&signature={signature}&event={event}&sub1={sub1}&sub2={sub2}&sub3={sub3}&sub4={sub4}&sub5={sub5}&sub6={sub6}&sub7={sub7}&sub8={sub8}&sub9={sub9}&sub10={sub10}&gaid={users_advertising_id}&clickIp={clickIpaddress}&clickDatetime={clickDatetime}&conversionDatetime={conversionDatetime}&timeZone={timeZone}&callback_type={callback_type}
```

{% endcode %}

## **Available Macros (Placeholders)**

| Macro                  | Description                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `{user_id}`            | Unique identifier of the user from your app (sent in click URL).                           |
| `{offer_id}`           | Unique identifier assigned to the offer in our system.                                     |
| `{offer_name}`         | The name/title of the offer that generated the conversion.                                 |
| `{payout}`             | Total revenue earned from the event.                                                       |
| `{sig}`                | A secure hash signature generated for verifying the authenticity of the postback data.     |
| `{event}`              | Name of the event or goal triggered (e.g., registration, level\_completed).                |
| `{sub1}` - `{sub10}`   | Custom parameters you passed in the click URL to help identify the user or campaign.       |
| `{clickDatetime}`      | Date and time when the user clicked the offer link.                                        |
| `{conversionDatetime}` | Date and time when the conversion (e.g., purchase, install) happened.                      |
| `{timeZone}`           | Time zone in which the click and conversion timestamps are recorded.                       |
| `{callback_type}`      | Type of callback (e.g., 1 = Api Callback, 2 = Direct offer Callback, 3 = iFrame Callback). |

**Example**

`clickId`= `123`

`offer_id`= `123`

`offer_name`= `Test_game`

`payout`= `500`

`signature`= `45786sdg458-sdg465-659s465sdg-465ery98bm-65fb798sdg32dv`

`event`= `Complete_level_X`

`clickDatetime`= `202X-0X-0X XX:XX:XX`   

`conversionDatetime`= `202X-0X-0X XX:XX:XX`

`timeZone`= `IST`

`callback_type`= `1`

PostbackURL -> `https://www.example.com/postbacks/postback_file_name.php?clickId =123&`offer\_id`=123&`offer\_name`=Test_game&payout=500&signature=45786sdg458-sdg465-659s465sdg-465ery98bm-65fb798sdg32dv&event=Complete_level_X&clickDatetime=202X-0X-0X XX:XX:XX&conversionDatetime=202X-0X-0X XX:XX:XX&timeZone=IST&callback_type=1`

## Test Callback Tool

We provide a dedicated **Test Callback Tool** so you can safely verify your callback configuration before going live.

<figure><img src="/files/g8LV84cGq5UkZ3W9HNkW" alt=""><figcaption></figcaption></figure>

#### Key Features:

* Safely test your callback URL without affecting live data.
* Instantly simulate user actions and reward payouts.
* Debug and validate parameters directly from the dashboard.

#### Input Fields:

* **User ID** → Simulates a user session.
* **Custom Parameters** → sub1=abc\&sub2=123\&sub5=xyz

<figure><img src="/files/XjcTK7KnvoCUSvBpJYRE" alt=""><figcaption></figcaption></figure>

#### How It Works:

1. Enter the **User ID** (this must match the User ID used in your SDK initialization).
2. Enter the **Custom Parameters** ( This is extra params which you can use to track conversions )&#x20;
3. Click **Send** **Test Postback**.

ℹ️ **Note**: Make sure the callback endpoint is correctly configured to receive and validate all required parameters.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.playtimeads.com/api-integration/setup-postback.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.