Getting Started

Configuration

Each game has a webhook URL property, webhook_url. This is the URL that will be called to pass information along to you for different events. You provide this when a game is created and you can update it via the API or the web interface.

In addition to the webhook URL, a game also has a webhook secret property, webhook_secret. This secret is meant to be used to validate any webhook calls you receive.

A game requires neither a webhook URL nor a webhook secret, but no webhook calls will be made unless they are both provided.

Once your game has a valid webhook URL and webhook secret, then the webhook will be called for each event we fire.

How they work

There are certain events that will occur that you may find interesting. Whenever one of these takes place, we will pass that information along to you. Probably the most interesting event is whenever a player has earned an achievement. When this happens, you will be notified at the webhook URL you entered with the information about the earned achievement, eg. the player and the achievement that was earned and any related rewards.

At this point, you can do whatever you want or need to do with the information. Typically, you will then notify the player that they have earned an achievement. You may want to handle any reward that might be associated with the achievement.

The webhook itself works by firing a POST request to the game's webhook URL property. The request's payload will have all of the event's relevant data. For details about the payloads, please look at the documentation for each event.

Authentication

The webhooks that we send will be signed by the webhook secret, which you should have provided during game creation or modification.

While you don't have to validate incoming webhook requests, we highly recommend that you do so.

Retries

If we send a webhook and receive a 2xx status code, then we will consider the webhook successful. If, however, any other status code is returned or if no response is made within 3 seconds, then we will consider the webhook failed.

Failed webhooks will be retried a maximum of 3 times. Prior to each retry, we will wait a small-but-increasing period of time: 10 seconds before the first retry, 100 seconds before the second, and 1000 seconds before the third and final.

If all retries have failed, then that particular event will not be sent again.

Authentication and Signing

Each time we make a webhook call, we pass a header called X-R4nkt-Signature, which will contain a signature that your webhook handler can use to validate the incoming request. The signature is generated using the HMAC-256 method, like so:

$signature = hash_hmac('sha256', $payload, $secret);

$payload is the JSON-formatted body of the POST request for the specific event.

$secret is your game's webhook secret setting.

hash_hmac() function is a PHP function that is used to "[g]enerate a keyed hash value using the HMAC method".

The $signature value that is generated must match the value passed in the R4nkt-Signature header. If it does not, then the webhook is not valid.

The sample code above that is used to determine the signature is in PHP, but this can be done in many languages. Here are some examples.