> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playbackrewards.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Postbacks

When a user completes a conversion event (e.g., an install, milestone, or purchase), Playback sends a server-to-server postback to the URL you provided to us during onboarding.

This allows you to:

* Record conversions and rewards in your own systems
* Attribute revenue and suggested user payouts to the correct user
* Optimize your traffic and placements based on performance

## **Request Structure**

When a real event occurs, Playback will replace the macros (e.g., `{user_id}`, `{transaction_id}`) with actual values.

The key names can be customized, or you can use the default names. Please ensure that no special characters should be included in the values, otherwise our backend may transform the request, which could cause issues with the payout.

**Default**

`GET` / `https://example.com/example?userId={userId}&pbUserId={pbUserId}&transactionId={transactionId}&suggestedUserPayout={suggestedUserPayout}&revenue={revenue}`

**Customized (Example)**

`GET` / `https://example.com/example?userId={userId}&id={transactionId}&playback_id={pbUserId}&userPayout={suggestedUserPayout}&revenue={revenue}&task={taskId}`

### Parameters

| **Parameter**         | **Detail**                                                          | **Format** |
| --------------------- | ------------------------------------------------------------------- | ---------- |
| `transactionId`       | Unique transaction identifier                                       | `String`   |
| `offerId`             | The offer ID that triggered the conversion                          | `String`   |
| `userId`              | Your user's unique identifier (passed in the tracking link)         | `String`   |
| `pbUserId`            | Playback's internal user identifier                                 | `String`   |
| `partnerId`           | Your partner ID                                                     | `String`   |
| `sub1`                | Sub-affiliate parameter 1 (pass-through from tracking link)         | `String`   |
| `sub2`                | Sub-affiliate parameter 2 (pass-through from tracking link)         | `String`   |
| `sub3`                | Sub-affiliate parameter 3 (pass-through from tracking link)         | `String`   |
| `type`                | The type of postback (REWARD for conversion events)                 | `String`   |
| `eventId`             | Unique event identifier for this conversion                         | `String`   |
| `eventName`           | Human-readable name of the event (e.g., 'Level 10 Reached')         | `String`   |
| `eventType`           | The type of conversion event (e.g., 'INSTALL', 'EVENT', 'PURCHASE') | `String`   |
| `eventValue`          | Optional value associated with the event (e.g., purchase amount)    | `Number`   |
| `eventTimestamp`      | Unix timestamp (in seconds) when the event actually occurred        | `Integer`  |
| `taskId`              | The task ID from the offer that was completed                       | `String`   |
| `taskConversionId`    | Unique identifier for this specific task conversion                 | `String`   |
| `revenue`             | Partner revenue for this conversion in USD (e.g., 4.98)             | `Number`   |
| `suggestedUserPayout` | Suggested amount to reward the user in USD (e.g., 1.50)             | `Number`   |

**Example Response URL:**

`https://example.com/example?userId=f3069c9ef82c4579&transactionId=e8525f9b-3dd3-4319-bdda-c1e1f375f5bf&revenue=12.00&suggestedUserPayout=1.20`

eventType can be used to detect the type of event that triggered the postback. installs will come with eventType=INSTALL

## Security

### IP Whitelisting

When we make payout request to partners, we send an HTTP request from the following set of IPs.

```text theme={null}
34.19.25.125
34.168.97.45
34.83.24.217
```

To enhance security, use these IP addresses for IP-level blocking on endpoints receiving Playback's postback requests. Allow only these specific IPs access.

### Signature

We send the following request headers that you may use to verify the authenticity of the request

* webhook-id
* webhook-timestamp
* webhook-signature

The webhook-signature value is produced from `hmac-sha256("<webhook-id>.<webhook-timestamp>.<ordered-search-params>", <secret-key>)` where

* `hmac-sha256` is the function/library call to produce a HMAC signature with the SHA256 algorithm
* `webhook-id` is the webhook-id header value
* `webhook-timestamp` is the webhook-timestamp header value
* `ordered-search-params` is all the request params in the request URL ordered by key in ascending order
* `secret-key` is the shared secret key

To verify the webhook-signature header is valid, recompute the signature on your end, then compare it with the webhook-signature header value. Use a constant time comparison function to compare the calculated signature with the expected signature to prevent timing attacks

We follow the standard webhook convention. You can read more details on the signature structure and how to validate in the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/bece768d960f09e242f5cd5686d859e475d6b478/spec/standard-webhooks.md#verifying-webhook-authenticity).

## Delivery

**Retry Logic**

If we receive a 4xx / 5xx from your endpoint, we have an established retry logic for the failed postback requests.

If a request fails, we retry after 10 minutes. A second failure prompts a retry in another 10 minutes. Subsequent failures lead to retries every 2 hours from the initial failed attempt. After 12 hours we stop retrying the request.

<Info>
  If you observe an extended period of unsuccessful requests, contact your Playback Direct rep for further investigation into the issue.
</Info>

We also have alerts and logging placed on our side. If certain thresholds are met where consistenst retries are necessary, we may temporarily pause offers and follow up with you to resolve the underlying issues.