Teak Reward Endpoint

What is the Teak Reward Endpoint?

To issue virtual currency or items in response to a player clicking on a notification, email, social post, or Teak Link, you must set up a server endpoint that can receive a form POST request from Teak. This server-side endpoint must:

  • Validate the request

  • Issue the specified rewards to the player

  • Respond to the request and indicate success or failure

The Request

Teak will issue a POST request to a specified endpoint. There is only one endpoint per app, and it is set as the "Server Endpoint" under "Server to Server Communication" in your app’s settings.

The request will have the following parameters set in the POST body with the application/x-www-form-urlencoded Content-Type:

app_id

The Teak App ID of the application

clicking_user_id

The game assigned player id of the player who has clicked on a notification, email, or Teak Link

event_id

A globally unique identifier specific to issuing this reward to this player

post_id

A 64 bit integer that identifies the notification, email, or Teak Link that the player clicked on

post_type

A string identifying the notification, email, or Teak Link in the Teak Dashboard. Typically this will be the Name of a Message or Link.

posting_user_id

The game assigned player id of the player who shared the post or request, or 0 if this reward is from an App to Player communication such as a notification, email, or Link.

reward

A JSON blob describing what your endpoint should grant the player. The format is {"internal_id" : quantity, "another_internal_id" : quantity}. For example, {"coins" : 25, "energy" :10 }

timestamp

The UNIX time at which Teak first attempted to grant this reward

signature

A SHA256 HMAC signature of the request built as follows

POST\n
{{teak_reward_endpoint_url}}\n
{{key}={{value}}&{{key2}}={{value}}

All keys are sorted alphabetically, and the entire string is signed using the Server to Server Teak App Secret (available under "Server to Server Communication in your app’s settings). The signature is base64 encoded, and CGI escaped. In ruby, this looks like:

string_to_sign = "POST\n#{teak_reward_endpoint_url}\n"
sig_keys = callback_parameters.keys.sort
string_to_sign += sig_keys.map { |k| "#{k}=#{callback_parameters[k]}" }.join('&')
signature = CGI.escape(Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new("sha256"), teak_server_secret, string_to_sign)).strip)

Validating the request

Your server must compute the signature using the above method and compare it to the signature passed in by Teak to validate the request. If the signatures do not match, the request is invalid, and the endpoint should not grant the player any rewards.

Furthermore, you should confirm that the player has not already been granted a reward with the given event_id. If a network failure or other intermittent error occurs, Teak will retry its request to your server endpoint. When doing so, all parameters, including event_id, will be identical. If the player has already been granted a reward with the given event_id, return a successful response and do no further processing

Issuing the Reward

Once the request has been validated, you must JSON decode the 'reward' parameter. This will be a dictionary of the internal id of the reward and the quantity. For example, many games internally refer to their earned and purchased currencies as "softCash" and "hardCash", while the user-facing names may be "Coins" and "Gold". In the reward dictionary, Teak will use the internal "softCash" and "hardCash" names. An example reward parameter would be

{"softCash" : 50, "hardCash" : 10}

The reward parameter may include any number of rewards and quantities. It is important that your reward endpoint properly grants the user all specified rewards.

Responding to the request

The server endpoint must respond with HTTP status code 200 and the string TEAKOK anywhere in the response body for Teak to consider the request successful. If the status code is not 200 or the string TEAKOK does not appear in the response body, Teak will retry the request 16 times with an exponential backoff over approximately three days. Each retry will be completely identical. No parameters will ever change between retries.

Testing the endpoint

You can test that your endpoint works from the 'Bundles' tab on the Rewards page for your app in Teak. Create a bundle to test with (we recommend one that gives out a variety of currencies and items, if applicable) and then click 'Test.'

In the modal that pops up, enter a player id in User Id: and 0 in Posting User ID, then click Preview. Teak will attempt to grant the reward by POST-ing to your server and will show the POST request made, the string which Teak signed with your Server to Server key, and how the server responded. If your server responds with 200 and TEAKOK in the body, and you confirm that the player was granted the items, you’re ready to ship!