Getting Started
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 been awarded a badge. When this happens, you will be notified via webhook of the event along with relevant information, 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 been awarded a badge. You may also want to handle any associated rewards.
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.
Configuration
Your game's webhook settings can be configured and tested in the game dashboard's webhook settings panel. It consists of two settings:
Webhook URL: This is the URL that will be called to pass information along to you for different events. A new game has no webhook URL. You must set this manually.
Webhook secret: This secret is used to validate any webhook calls you receive. A random secret is generated for all new games, but you can always change it to something more preferable.
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.
Be sure to take advantage of the "test webhook" functionality that you can find in the game dashboard's webhook settings panel.
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:
$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 X-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.
Please note that the signature is not encoded, Base64 or otherwise.
Last updated